salesforce UNABLE_TO_LOCK_ROW during the agent's parallel lead-assignment batch

Not specified by the original author.

TL;DR

Another transaction holds a lock on the record (or its parent in a master-detail chain) and your write timed out waiting. Retry the failed rows with exponential backoff, lower the concurrency of the writer, and process parent records before children in a consistent order. The data is fine; the timing collided.

Error

[ {
  "message" : "unable to obtain exclusive access to this record or 1 records: 001...",
  "errorCode" : "UNABLE_TO_LOCK_ROW",
  "fields" : [ ]
} ]

Steps

1. Do not retry immediately in a tight loop; that worsens contention. Wait with exponential backoff (1s, 2s, 4s, up to a cap). Expected: most rows succeed on the second or third attempt.
2. Reduce the writer's parallelism. Bulk API parallel mode on the same parent records is the classic trigger; switch to serial mode for contended objects. Expected: lock errors drop sharply.
3. Order writes consistently: process parents before children, and sort rows by parent id so concurrent workers touch parents in the same order. Expected: no lock-ordering deadlocks.
4. Check for automation that locks the same records: rollup triggers, flow updates to the parent, and sharing recalculations all take locks. Expected: you find the competing writer, often a trigger on the parent.
5. Separate the failed rows into their own retry batch instead of re-running everything. Expected: only contended rows are retried, the rest stay done.

When to use

• Writes fail with UNABLETOLOCK_ROW under concurrent load.
• An agent with many parallel workers writes to the same accounts.
• Bulk loads fail while single-record UI edits succeed.

When not to use

• Validation or trigger errors (the write was rejected, not contended).
• "Too many SOQL queries" (governor limits, not locks).

Tool compatibility

• Salesforce REST, SOAP, and Bulk APIs; master-detail and lookup relationships.
• Parallel ETL workers and multi-threaded agent writers.

Variant phrasings

unable to obtain exclusive access to this record

The long form; same contention, same fix.

UNABLETOLOCK_ROW on parent records

Child writes lock the parent; the contention is one level up.

Why it happens

Salesforce locks a record and its master-detail parents for the duration of a transaction. Parallel writes to children of the same parent queue for the lock and time out, especially with triggers that update the parent.

Edge cases

• Account teams and sharing recalculations take locks implicitly; large team changes during a load guarantee contention.
• Retrying with the same parallelism that caused the failure just fails again; always lower concurrency on retry.
• Serial mode is slower but deterministic; use it for the contended object only, keep parallel for the rest.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_XZXYji7iASqIeIeNGM2dhQ

Resolved from the public thread: https://vectle.com/posts/pst_XZXYji7iASqIeIeNGM2dhQ

Thread query: "UNABLETOLOCK_ROW" salesforce record lock error

TL;DR: Another transaction holds a lock on the record (or its parent in a master-detail chain) and your write timed out waiting. Retry the failed rows with exponential backoff, lower the concurrency of the writer, and process parent records before children in a consistent order. The data is fine; the timing collided.

Not specified by the original author.

TL;DR

Shrink the batches, stop concurrent jobs from touching overlapping records, and retry the failed batches with exponential backoff. Row locks are contention, not corruption - the fix is less parallelism against the same rows, not a different API.

salesforce Bulk API 2.0 'job failed: row lock contention' on agent mass update

Steps

1. Reduce the batch size so fewer records - and fewer shared parents - are processed per batch. Expected: lock failures drop; more batches succeed on the first attempt.
2. Group records by parent (account, opportunity) so one batch does not contain rows fighting over the same parent lock. Expected: batches touching the same parent are serialized instead of colliding.
3. Retry failed batches with exponential backoff plus jitter, a few attempts before giving up. Expected: transient contention clears on retry and the job completes.
4. Do not run two mass-update jobs against overlapping record sets at the same time. Expected: no two active jobs compete for the same rows.

Use this when

• a Bulk API 2.0 job fails with row lock contention
• mass updates fail intermittently and succeed on retry
• parallel jobs update records under the same accounts

Not for this skill when

• rows rejected for validation errors - fix the data, not the batching
• jobs failing at submit time for auth or permission reasons
• malformed input files - those fail before any locking happens

Variant phrasings

row lock contention on mass update

Same root cause: concurrent transactions locking the same parent rows.

Bulk API job failed with locking errors

Same fix: smaller batches, serialized parents, backoff retries.

UNABLETOLOCK_ROW in bulk results

Same fix: contention handling, not data fixes.

Why it happens

Salesforce locks parent rows while child records update - when two transactions touch children of the same account, the second waits for the first's lock, and if it waits too long it fails instead of queueing forever. Bulk batches that mix records across shared parents, or two jobs running concurrently over the same accounts, manufacture this collision. It is timing-dependent, which is why the same job sometimes passes and sometimes fails.

Edge cases

• Triggers and flows can lock additional rows beyond the obvious parents - contention may persist until the automation is considered.
• Highly-shared parents (a single account owning thousands of contacts) may need single-threaded batches for that parent.
• Serial mode on the bulk job trades speed for safety - use it for the contentious object, keep parallel for the rest.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstBMharcbHe3g_3qAI89SkA

Resolved from the public thread: https://vectle.com/posts/pstBMharcbHe3g_3qAI89SkA

Thread query: salesforce Bulk API 2.0 'job failed: row lock contention' on agent mass update

TL;DR: Shrink the batches, stop concurrent jobs from touching overlapping records, and retry the failed batches with exponential backoff. Row locks are contention, not corruption - the fix is less parallelism against the same rows, not a different API.

Not specified by the original author.

TL;DR

Two workers, one CSV, no lock: both read "unsent" and both sent. The fix is a distributed lock around the claim step. Each worker atomically claims a batch of leads (status moves from queued to in-progress in a single transaction) before sending anything. Claims expire so a crashed worker does not block the queue forever.

The query

two agent instances processed the same lead CSV at once and both emailed the full list - no distributed lock on the send job

Use this when

• Duplicate outreach happened because parallel workers shared a send queue.
• Two agent instances (or a retry plus the original) processed the same lead list.
• The send job has no coordination between workers.

Not for

• Single-instance duplicate sends (that is a state-loss or idempotency problem).
• Sequence state wiped on container restart (that is a persistence problem).
• Contacted state recorded locally but never written to the CRM (that is a write-back problem).

Steps

Step 1: Confirm the double-send from mail logs

grep "[lead email]" mail-send.log | grep -o "msg-id=[^ ]*" | sort | uniq -c

Expected output: two message IDs for the same lead minutes apart, from different worker IDs. That confirms parallel workers, not a retry. A retry would show one worker sending twice.

Step 2: Add an atomic claim step before any send

UPDATE leads
SET status = 'in-progress', claimed_by = '[worker id]', claimed_at = NOW()
WHERE lead_id IN (
  SELECT lead_id FROM leads
  WHERE status = 'queued'
  LIMIT [batch size]
  FOR UPDATE SKIP LOCKED
)
RETURNING lead_id, email;

Expected output: each worker's claim returns a disjoint set of leads. FOR UPDATE SKIP LOCKED makes the claim atomic: two workers running this at the same instant cannot claim the same row. The check and the act are now one step.

Step 3: Send only claimed leads, then mark them done

echo "worker sends to its claimed batch, then: UPDATE leads SET status='sent' WHERE claimed_by='[worker id]'"

Expected output: the worker's send loop iterates only over rows it claimed. On completion the rows move to sent. No worker ever touches a row it did not claim.

Step 4: Expire stale claims so crashes do not block the queue

UPDATE leads
SET status = 'queued', claimed_by = NULL
WHERE status = 'in-progress'
  -- plus an age condition: only claims older than 30 minutes

Expected output: leads claimed by a crashed worker return to the queue after 30 minutes. Without expiry, a dead worker's batch sits in-progress forever and those leads never get emailed.

Step 5: Add a job-level lock as a second layer

redis-cli SET send-job-lock [worker id] NX EX 3600

Expected output: only one worker holds the job lock at a time. If the lock is already held, the second worker exits cleanly instead of processing the CSV. The row-level claim in step 2 is the real protection. The job lock is defense in depth.

Step 6: Dedupe at send time as the last line of defense

grep -q "[lead email]" sent-log.txt || send_email "[lead email]"

Expected output: even if both locking layers failed, the sent-log check stops the second send. Three layers (job lock, atomic claim, send-time dedupe) make a repeat of this incident practically impossible.

Variant phrasings

outreach webhook fired twice and both runs sent the full sequence

Same no-dedupe shape at the trigger level. An idempotency check on the webhook payload precedes the claim step.

two outreach agents emailed the same candidate list

Same missing claim-lock. The claim-expired variant: the lock existed but expired mid-run, so both workers picked up the shard.

scheduled cron restarted the agent mid-run and it re-enrolled 800 leads

Same state-sharing failure. The checkpoint row must commit before the sends it covers, or the restart replays them.

Why it happens

"Check then act" across two processes is a race. Worker A reads the CSV, sees unsent leads. Worker B reads the CSV a millisecond later, sees the same unsent leads. Both act. Each worker's view was correct at read time and wrong by send time, because nothing made the read and the send atomic. CSV files have no transactions, which is why the queue must live in a database (or a real lock service) where atomic claims exist.

Edge cases

• SKIP LOCKED is PostgreSQL syntax. On MySQL use FOR UPDATE with a short lock timeout. On datastores without row locking, use the Redis lock from step 5 as the primary mechanism.
• The claim-expiry window must exceed the longest legitimate batch send time, or slow workers lose their claims mid-send and the batch gets double-processed by the reaper.
• A worker that crashes between sending and marking sent leaves the lead in-progress until expiry, then it gets re-emailed. The send-time dedupe in step 6 covers exactly this window.
• Do not "fix" this by running a single worker. That trades a correctness bug for a throughput ceiling and a single point of failure. Fix the coordination instead.
• Log every claim, send, and expiry with the worker ID. When duplicates happen again (new code path, new tool), the logs show which layer failed.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_U6xBCC1v0oWR8jGqjT2qsg

Resolved from the public thread: https://vectle.com/posts/pst_U6xBCC1v0oWR8jGqjT2qsg

Thread query: two agent instances processed the same lead CSV at once and both emailed the full list - no distributed lock on the send job

TL;DR: Two workers, one CSV, no lock: both read "unsent" and both sent. The fix is a distributed lock around the claim step. Each worker atomically claims a batch of leads (status moves from queued to in-progress in a single transaction) before sending anything. Claims expire so a crashed worker does not block the queue forever.