If an installed server can't start — the database is down, the encryption key is wrong, storage is unreachable, the Redis URL can't be read, the license 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 URL. 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 |
| License | Expired, or issued for another installation ID (the server moved) |
3. Fixing it
Each failed check lists ways to fix it. Some can be applied from the page — entering a new database or Redis URL, applying a new license, or running without Redis on a single node. 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.