Fix a Salesforce deployment stuck in Pending

What Pending actually means

Salesforce processes deployments serially per org. One deploy — yours, a colleague's, a CI pipeline's, or a packaging job you cannot see — holds the slot, and everything else waits. While it waits, a deployment reports status Pending with zero components processed. That is the normal, healthy state for a queued job.

The problem is that a second, unhealthy state looks exactly the same. Occasionally the platform accepts a deployment request, returns a job ID, and then never schedules the job. It stays Pending indefinitely. Nothing times out, nothing errors, and the job never starts. From the outside — same status, same zero counters — the two are indistinguishable.

So the diagnosis is not "is my job Pending?" It is "is anything else running?" If yes, wait. If no, and yours has been Pending for more than a few minutes without starting, it has been dropped.

Step 1 — Look at the org's deploy queue

In the browser: Setup → Deployment Status. It lists in-progress, queued, and completed deployments for the org, including ones started by other people and by CI. This is the single most useful screen for this problem and the one most people never open.

From the Salesforce CLI, report on your own job:

# Report on a specific job
sf project deploy report --job-id 0Af...  --target-org staging

# Report on the last deploy you started from this machine
sf project deploy report --use-most-recent --target-org staging

Note what the CLI can and cannot tell you: it reports the state of your job. It does not show you what else is in the queue ahead of it, which is the fact you actually need.

Step 2 — Decide: queued, or dropped?

• Another deployment is InProgress. Yours is queued behind it. Wait. Cancelling and resubmitting here achieves nothing except putting you at the back of the same queue.
• Nothing is running, yours has been Pending for several minutes, and the component counters are still zero. The job was never picked up. Cancel and resubmit.
• Yours is InProgress with counters moving. It is not stuck, it is slow — usually because it is running Apex tests in the org. Watch it rather than killing it; a cancelled deploy with tests half-run wastes the whole test cycle.

Step 3 — Cancel and resubmit

Cancelling is safe for a job that never started: no components were deployed, so there is nothing to roll back.

# Cancel the dropped job
sf project deploy cancel --job-id 0Af... --target-org staging

# Resubmit the same source
sf project deploy start --source-dir force-app --target-org staging

One caution: only cancel a job you own. Deployment Status shows everyone's deployments, and cancelling a colleague's release because it is in your way is a conversation, not a command.

The Nimbus way

Nimbus reads the same queue and does the comparison for you. nimbus release status shows the org's in-flight deployments with their queue positions and recent terminal history, and calls out a job that is genuinely stuck — Pending beyond the threshold, never started, with nothing running that explains the wait — along with the remedy.

# The org's deploy queue, with stuck-Pending diagnosis
nimbus release status --target-org staging

# Machine-readable, for a CI gate
nimbus release status --target-org staging --json

# Cap the completed history; active jobs are always shown in full
nimbus release status --target-org staging --limit 5

This command is read-only and deliberately not Pro-gated. Knowing that your deploy is stuck is a safety property, and safety defaults do not sit behind a licence.

To follow a job to its conclusion — queue state, component counters, test counters — point nimbus release watch at a job ID or a release receipt. It polls until the deployment reaches a terminal state and exits with a code that mirrors the outcome, so CI can gate on it. Watching never cancels or resubmits anything, which is why it is safe to point at anyone's deployment, including one you did not start.

# Follow any deploy to its terminal state
nimbus release watch 0Af... --target-org staging

# Or follow the job a Nimbus receipt validated
nimbus release watch <releaseID> --target-org staging

Requeueing a stuck release, without re-validating

If the stuck job belongs to a Nimbus release — one you validated with nimbus release validate — nimbus release requeue does the cancel-and-resubmit as a single step, and resubmits the stored bundle. The retried payload is byte-identical to the payload Salesforce validated, so you do not re-validate and you do not risk shipping a worktree that moved underneath you.

# Cancel the stuck Pending job and resubmit the validated bundle
nimbus release requeue <releaseID> --target-org staging

# Stable JSON result, for pipelines
nimbus release requeue <releaseID> --target-org staging --json

Requeue 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 — watch it instead. A finished one asks you to revalidate. And it takes a receipt, never a bare job ID: deployments Nimbus did not create are diagnosed by release status but never touched, because cancelling a colleague's deploy is a human decision.

Requeue is part of the Pro release workflow. release status and release watch are not.

Not getting into this state

• Attend your deploys. While Nimbus is attending its own job it recovers a scheduler-dropped Pending automatically. The manual requeue path exists for the job that stuck while nothing was watching it — typically a CI run that fired and forgot.
• Do not run concurrent deploys against one org. They do not run concurrently; they queue. Serialise the pipeline instead of discovering the queue at 3pm on a release day.
• Stop paying for org-side test time you already paid for locally. The longest deploys are the ones running Apex tests in the org. If those tests already ran on your machine in seconds, the org-side run is a validation step, not your feedback loop. That is the whole argument of running Apex tests locally.