Troubleshooting

Start with the explanation in the web interface

Every failed job, item, sync and verification in Restow says what happened, why, and what to do about it, with a link to the right settings page where there is one. Under Technical details it lists what a support case needs: the HTTP status, the Microsoft Graph error code and the request IDs, with secrets removed. Look there first. Failure explanations lists the causes and what to do about each one. For servers and clients backed up with the agent, see Endpoint backup troubleshooting.

The links in these explanations lead to this page by default. RESTOW_DOCS_TROUBLESHOOTING_URL points them at your own runbook instead.

Installation

• docker compose up -d fails or a container keeps restarting. Check docker compose ps and docker compose logs <service>. The most common cause is a missing required value in .env. See Get started → Fill in the required values; Compose refuses to start postgres at all if POSTGRES_PASSWORD is unset, and caddy if RESTOW_APP_DOMAIN is unset.
• Compose stops with set RESTOW_IMAGE in .env or set RESTOW_WEB_IMAGE in .env. The release stack needs both image lines, for example ghcr.io/restow-backup/restow:0.1.0 and ghcr.io/restow-backup/restow-web:0.1.0, in .env. See Get started → Fill in the required values.
• Caddy can’t obtain a certificate. RESTOW_APP_DOMAIN must resolve (A/AAAA) to the host, and ports 80/443 must be reachable from the internet for the Let’s Encrypt challenge. This only applies in public mode.
• api, worker or scheduler refuses to start with a Row Level Security error. The application role (DATABASE_URL) must not be a superuser and must not be able to bypass RLS; this check runs at startup on purpose. Re-check the three database roles in Get started.

Backups

• A job is stuck or very slow. Check the job’s progress for a throttling notice: Microsoft Graph throttling is shown, not hidden, and the first backup of a large tenant can legitimately take days. If there is no throttling notice and no progress, check /healthz and /readyz, and confirm the worker and scheduler containers are running.
• A backup shows as failed. Restow marks a backup as failed if its scheduled restore verification did not succeed, even if the backup run itself reported success. Treat that as the accurate status, not a false alarm. See Backups and schedules.

Restores

• A restore did not go where you expected. By design, restore is built not to overwrite an existing original; if something with the same name already existed in the target location, Restow will have written the restored item in alongside it instead (a new folder for mail, a renamed file). Check the restore’s log entry, or its job detail page, for exactly which mode was used and where the item went. See Backup and restore.
• You cannot find a restore in the audit log. Every restore is recorded in every edition, but the audit log viewer is a Business and Service Provider feature. If you have the viewer and cannot find one, check that you are looking in the correct tenant (Service Provider edition) and time range.

Archive and journaling

• The Archive page says “Receiver not running”, “No reports yet” or “No report for more than 24 hours”. The reason and the checks are on Exchange journaling: the TLS certificate the receiver needs, DNS, TCP port 25 from the internet, the Microsoft 365 connector and the journal rule, and the mailbox for undeliverable journal reports.
• The receiver does not start after you set JOURNAL_SMTP_PORT. It starts only with a certificate and key of your own (JOURNAL_TLS_CERT_PATH, JOURNAL_TLS_KEY_PATH); the api log names the file that is missing, unusable or expired. See Exchange journaling → TLS certificate.

Sign-in

• Passkeys are not offered yet. Passkeys only appear once your domain is verifiably and cleanly connected: valid HTTPS certificate, matching origin. Until then, sign-in uses the emergency password path with mandatory TOTP. Re-run the domain check after fixing DNS or certificates (see Setup wizard → Passkey readiness).
• A Microsoft 365 admin-consent grant looks incomplete. Restow reports exactly which permissions were and were not granted; re-run the consent flow as an administrator with sufficient privileges in the tenant (see First steps).
• End users can’t sign in with their Microsoft account. That sign-in path is built but not enabled in the current beta; use a passkey or the emergency password path instead.

Integrations and licensing

• A webhook shows as “Failing”. Open its delivery log for the exact HTTP status or connection error from each attempt. A target in a loopback or private network is refused unless the operator explicitly allowed it. See Integration API → Webhooks.
• A license key is rejected. Check that the key was issued for this installation’s own installation ID (shown next to License → Install a key). A key issued for a different installation, or one that fails its Ed25519 signature check, is refused rather than partially applied. See License and editions.

Where to look next

• The audit log, for who did what and when.
• Your notification mail transport’s test-send result (SMTP or Microsoft Graph sendMail), configured during setup. A failing transport means operational alerts are not reaching you even if everything else is healthy.
• The status and roadmap page, if you are unsure whether something is meant to exist yet at all.