---
title: "Troubleshooting"
description: "The failures people actually hit - verify timeouts, drift, protected releases - and the fixes."
canonical: "https://orbit-handbook.sitesmojo.com/docs/troubleshooting/"
---

# 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:

```bash
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](/docs/deployments/), or
see how we run Orbit on itself in
[Field Notes](/blog/dogfooding-orbit-on-orbit/).