Skip to main content

Rollback

An update did not come up. The api container keeps restarting, or it never turns healthy, or the app won't load after docker compose up -d. This is the path back to the last version that worked.

First, confirm it is the api​

Check what the containers are doing:

docker compose ps

An api that is restarting, or running (health: starting) for well past a minute and never reaching healthy, is the signal. Read why:

docker compose logs --tail=100 api

A failed migration crashes the boot on purpose (an api will not serve against a half-changed schema), and the log line names the migration that did not apply. That is the difference between "a migration failed" and "the app is just slow to start". Health and status covers reading these signals in more detail.

Step back to the previous version​

Because migrations are additive (an older image runs fine against the newer schema, see Versioning and breaking changes), rolling the images back is the fix. Set COBBLR_VERSION in your .env to the version you were on before the update:

# .env
COBBLR_VERSION=2026.8.0
Pin a real version, not a moving tag

latest, stable and nightly all move, so pointing COBBLR_VERSION at one of them rolls nothing back. Pin the numbered release you were on, like 2026.8.0, or a dated nightly snapshot like nightly-2026-08-10. If you never pinned and cannot tell which version you were running, docker compose logs api | head from before the update names it, and failing that your most recent backup is the way back. See If it still won't start below.

Then pull that version and recreate:

docker compose pull && docker compose up -d

The previous api comes up against your existing database and you are running again. Your data was not lost: a migration that failed rolled back its own transaction, and the additive rule means the schema an older image expects is still present.

If it still won't start​

  • Watch the logs while it boots. docker compose logs -f api shows the startup sequence live. If the same migration error repeats after you pinned an older version, you may have moved the pin to a version that is itself newer than where you started; set it lower.
  • Restore a copy. If the database itself is in a bad state, restore your most recent dump into a clean instance. See Backups and restore tests, and this is the moment the monthly restore test earns its place: you want to find out a backup is good long before you need it.
  • Report the version pair. A clean update that fails is worth reporting with the from-version and to-version and the migration name from the log, so the bad migration can be fixed for everyone.