Troubleshooting

The failures people actually hit, and what to do about each.

orbit doctor first

Nine times out of ten this names the problem and prints the fix:

orbit doctor

Deploy fails at verify

Your service came up but never answered health.path in time. The
environment is untouched - that is the design. Check:

• Does health.path exist in the new build? (The classic: renamed
  /healthz, forgot orbit.yaml.)
• Is health.timeout shorter than your cold start?
• orbit logs --env staging --release <n> tails the discarded release, so
  the evidence survives the failure.

Plan shows changes you did not make

Someone changed the environment outside Orbit. Run orbit plan --json and
look at drift - Orbit lists what moved underneath it. Apply to reconcile,
or investigate before you do.

error: release is protected

The environment has protect: true and the deploy came without a
confirmation. In CI, add --yes deliberately - protection exists so a
human decides.

Rollback seems to have no effect

Check you rolled back the environment you think you did: orbit status
shows what is live everywhere. The second classic: a CI job redeploying
the bad release right after your rollback. Pause the pipeline first.

Still stuck?

Read the release story end to end in Deployments, or
see how we run Orbit on itself in
Field Notes.