The Salesforce deploy queue, explained

One lane, and you cannot see into it

The Salesforce Metadata API serialises deployments per org. Two jobs never execute concurrently against the same org, which is the right call — concurrent metadata writes to a shared schema would be a correctness disaster. The consequence is that every deployment on a busy org spends some of its life waiting for the one in front of it.

The part that hurts is that the wait is invisible. Setup → Deployment Status shows you deployments, but it is not a queue view: it will not tell you how many jobs are ahead of yours, or that the thing occupying the org right now is a colleague’s two-hour validation with all tests, or that the job it is showing as Pending stopped being scheduled twenty minutes ago. The CLI is no better placed. It polls the job you submitted and reports what that job says about itself, which is Pending, over and over, with no context.

A deploy that is politely waiting its turn and a deploy that is hung produce the same terminal output, the same Setup screen, and the same feeling. That ambiguity is the whole problem, and everything below is downstream of it.

The states, and what each one actually claims

• Pending — Salesforce accepted the request and has not begun executing it. Nothing has been written to the org. No test has run. This state carries no information about how long it will last or whether anything is ahead of you.
• InProgress — the job owns the org’s deployment slot and is working through components, then tests. From here component and test counters advance, which is the first point at which “is it moving?” has an honest answer.
• Succeeded / Failed / Canceled — terminal. The job is off the queue and the next one can start.

The single most useful thing to internalise: check-only validations share the queue with real deploys. A validation is not a lightweight preview that runs somewhere else — it occupies the same one-at-a-time slot and, if it runs the full test suite, occupies it for as long as a deployment would. On a team where CI validates every pull request against a shared org, most of your Pending time is spent behind validations that will never deploy anything.

What “stuck” precisely means

“Stuck” gets used for any deploy that is taking longer than the person watching it expected, which makes it useless as a diagnosis. It is worth pinning down to three simultaneous conditions:

1. The job is Pending.
2. It has never started — no component or test counter has advanced.
3. Nothing is running that would explain the wait. No other job holds the org’s deployment slot.

The third condition is the one you cannot evaluate from your own job’s status, and it is the one that does the work. A Pending job with a long-running validation in front of it is queued — behaving correctly, and cancelling it accomplishes nothing except losing your place. A Pending job with an empty org slot in front of it is a job the scheduler never picked up, and it will sit there indefinitely.

Add a duration threshold to condition one so that normal scheduling latency does not trip the diagnosis. Nimbus defaults to three minutes (nimbus.release.stuckPendingAfter); the exact figure matters less than having one, because “Pending for a few seconds” is just the queue working.

Why cancel-and-resubmit is safe — and exactly when

The folk remedy for a stuck Salesforce deployment is to cancel it and submit it again, and it usually works: the resubmitted job gets scheduled and runs immediately. The interesting question is not whether it works but why it is safe, because “cancel the deployment and try again” sounds like exactly the advice that leaves an org half-deployed.

It is safe for one specific reason: a job that never started has executed nothing org-side. No component was written, no destructive change applied, no test run. Cancelling it removes a request, not a partial result. There is nothing to roll back because nothing happened.

Every clause of that sentence is load-bearing, and each one marks a case where the remedy stops applying:

• An InProgress job must be left alone. It has begun writing components. Cancelling mid-flight is a legitimate operation, but it is a different one with a different risk profile, and it is not the fix for a queue that never started you.
• A finished job cannot be resubmitted. It produced an outcome; re-running it is a new deployment decision, not a recovery.
• The resubmitted payload must be identical. If the resubmission re-reads your working tree, you have quietly deployed something other than what was validated. The safe version resubmits stored bytes.
• Somebody else’s job is not yours to cancel. Cancelling a colleague’s deploy is a human decision with a human on the other end of it, regardless of what the queue says.

The queue, from the terminal

This is the gap Nimbus’s release commands close. nimbus release status reads the org’s deployment queue directly: each job’s position, live component and test counters, and recent history correlated with your local release receipts. A job matching all three stuck conditions is called out as stuck, with the remedy attached. It is read-only, and deliberately not Pro-gated — knowing your deploy is stuck is safety, and the safe default is never paywalled.

nimbus release watch follows a Salesforce job ID (0Af…) or a release receipt until it reaches a terminal state, printing queue state and counters, and mirrors the outcome in its exit code so CI can gate on it. Watching never cancels and never resubmits, which is why it is safe to point at anyone’s deployment — including the one that is blocking yours.

nimbus release requeue is the remedy, with the safety conditions enforced rather than documented. It takes a receipt, never a bare job ID, and refuses anything that is not provably the stuck case: the org must match the receipt’s fingerprint, and the job must be Pending and never started. A running job is left alone with “watch it instead”; a finished one asks you to revalidate. Because the resubmission is the stored bundle, the retried payload is byte-identical to what was validated.

# Is it queued, running, or actually stuck?
nimbus release status --target-org production

# Stable JSON for a scripted gate
nimbus release status --json --limit 20

# Follow a job — or a receipt — to its outcome.
# Read-only: safe on anyone's deployment.
nimbus release watch 0Af5g00000XXXXXCAA
nimbus release watch rel_20260720T141342_0397df68b0

# Cancel the stuck Pending job and resubmit
# the byte-identical validated bundle
nimbus release requeue rel_20260720T141342_0397df68b0

In practice you will rarely type requeue. While Nimbus is attending its own job it polls the org, streams progress, and — when that job sits Pending past nimbus.release.autoRequeueAfter (five minutes, up to nimbus.release.maxRequeues attempts) — cancels and resubmits the identical bundle by itself, recording every recovery attempt on the receipt. It asks for no re-confirmation, because nothing ran and the payload cannot drift. Deployments Nimbus did not create are diagnosed but never touched. The manual command exists for the case where a job stuck while nothing was watching it.

What to do the next time it says Pending

• Look at the org, not at your job. Your job’s status cannot distinguish queued from stuck. The queue can.
• Assume validations are the traffic. On a shared org, check-only runs occupy the same slot; the deploy in front of you may not be a deploy.
• Only requeue on all three conditions. Pending past a threshold, never started, nothing running to explain it. Anything else and the remedy is the wrong remedy.
• Resubmit stored bytes, not the working tree. Otherwise recovery silently changes what ships.
• Never cancel a job you did not submit without talking to whoever did.