If an installed server can't start (the database is down, the encryption key is wrong, storage is unreachable, the licence no longer matches) it doesn't just exit. It starts in recovery mode, finds what's wrong, and shows you how to fix it.
1. Open the recovery page
The server log shows a line like open the recovery page … recovery_url=https://…/recovery?token=…. Open that address. The key keeps the diagnostics private; set RECOVERY_TOKEN to choose it. Like the setup key, it is removed from the address bar once the page has read it.
2. What it checks
| Check | Common causes |
|---|---|
| Bootstrap file | The server was started with a different CONFIG_ENCRYPTION_KEY, or the file is damaged |
| Database connection | PostgreSQL is down, unreachable, or its credentials changed |
| Database schema | An upgrade's migration failed partway |
| Stored configuration | Wrong encryption key, or the wrong database |
| Redis | Redis is down or moved |
| File storage | Directory not writable, bucket missing, credentials expired |
| Licence | Expired, or issued for another installation ID |
3. Fixing it
Each failed check lists ways to fix it. Some can be applied from the page: a new database or Redis URL, a new licence, or running without Redis on a single server. The server tests the change, saves it encrypted, and restarts; the page reloads when it's back.
Recovery never changes data on its own. Repairs such as fixing a failed migration are described, not performed: take a backup first.
The server only enters recovery mode on a machine that was already set up. A brand-new installation always starts the setup wizard.