Troubleshoot an instance

Find your problem below and work through the checks in order. Don’t delete or move files to make an error go away. Keep the database, the files beside it, the assets folder, and your backups together, so nothing is lost while you work out what’s wrong.

Savorum doesn’t start

Read the error it prints when it starts. Common causes:

• an invalid SAVORUM_* value;
• a database that needs a newer or older version of Savorum;
• a database or assets folder that Savorum can’t reach, or that belongs to a different user or group than the storage setting expects;
• an invalid saved setting.

Check that the database and assets are on a local disk. A symlink or special file inside the assets folder also stops startup.

The health check fails

Check the service logs, then check the local address:

savorum healthcheck --url http://127.0.0.1:8080/api/v1/health

It fails with 503 when the database can’t be read. Savorum isn’t ready until the health check passes.

Nobody can sign in

1. Check that sign-in is on: --auth-enabled is off by default, and sign-in providers don’t load without it.
2. If Savorum stopped at startup, read the error. A provider file with an unknown field stops startup.
3. If passkeys stopped working, check whether the public address changed. Passkeys only work on the address they were added on. Go back to the old address, let people add passkeys at the new one, then remove the old ones.
4. If pages load but saving fails in the browser, set --public-url to the exact address the proxy serves. Savorum refuses changes from any other address.
5. If sign-in says 503 authentication-rate-limited, too many people are signing in at once. Savorum checks two passwords at a time. Wait a second and try again; the Retry-After header says how long.

If the administrator’s sign-in is lost, reset it from the server with savorum user reset-password --user-id ADMIN_USER_ID. See Recover administrator access.

An import doesn’t finish

Read the messages in the preview. PDF and photo import needs Poppler and Tesseract on the server; see Set up PDF and photo import. A web import needs a public web address: private addresses and addresses with login details are refused. If an import was interrupted, resume it, and give the original file again if Savorum asks.

The database is damaged or the disk is full

1. Stop changes, and keep the damaged files.
2. Verify a backup you know is good.
3. Restore it into a new, empty location.

Use check-database and scrub-assets only to find the problem. Nothing repairs or trims history automatically. See Free up space.

A restore stopped, or startup reports recovery

Don’t delete a lock, journal, -wal, or -shm file. Make sure nothing else is running Savorum, then start it again with the same database and assets paths. It uses its recovery journal to finish with either the complete old or the complete new data. If the journal is damaged or missing, Savorum stops so you can investigate.

See Back up and restore an instance for the safe steps.

Next: Command-line reference.