Docs / Troubleshooting

Troubleshooting

Start with these three commands. They answer most questions before you need to read a log.

CommandWhat it tells you
safegrd doctorChecks config permissions, whether the key pair is intact, whether the sink answers and Object Lock works on it, whether SafeGrd's server answers, the host's clock skew, and whether each surface opens with the credential its backup will use. On an enrolled host the result also shows in the console. Add --json for CI.
safegrd config validateChecks config syntax, permissions and surface definitions without running anything.
safegrd daemon statusFor each surface: what is due, what is failing, and when it last succeeded.
Which command to run first for each symptom. Nothing ran on schedule: safegrd daemon status. A backup or a drill failed: safegrd doctor. Snapshots are missing from the list: safegrd undelete --all. A restore cannot find the key: point --key-path at the key file. Nothing ran on schedule safegrd daemon status what is due, last success A backup or a drill failed safegrd doctor one line per check, a Fix Snapshots gone from the list safegrd undelete --all removes delete markers A restore cannot find the key --key-path <file> the key file, copied over
Where to start for each symptom. doctor prints a Fix: line under each check it knows how to fix. The sections below cover the rest.

Common failures

"Bucket does not support Object Lock"

Create a new bucket with Object Lock and versioning turned on. Most providers let you turn on Object Lock only when you create a bucket.

If your provider has no Object Lock at all (DigitalOcean Spaces, for example), set worm_mode: "NONE". Backups to that sink are then not locked, and anyone with a delete key can remove them.

A refused worm_mode

Write the value in uppercase: COMPLIANCE, GOVERNANCE or NONE.

"credential_held is no longer read"

Your config was written for an older CLI. A surface now says where its credential comes from in one credential block, and the error names the replacement for the old key:

See Configuration.

Config permissions rejected

Run chmod 600 ~/.safegrd/config.yaml. The file holds connection strings, so on POSIX hosts the CLI refuses to load it if its group or other users have any access to it.

Restore cannot find a key

On a recovery host, copy the key file over and point --key-path at it. The CLI looks for the private key in key_path, SAFEGRD_PRIVATE_KEY, --key-path or --private-key. The key is never stored in config.yaml.

My snapshots vanished

Under Object Lock they are almost certainly still there. A DELETE writes a delete marker that hides them. Run safegrd undelete --all to remove the markers. See Storage and retention.

IMAP certificate errors on a self-hosted server

Point the surface's ca_file at your internal CA bundle. You can also pass --email-ca-file to a one-off backup, or set SAFEGRD_EMAIL_CA_FILE. Certificate checks cannot be turned off.

Clock skew warnings

Run NTP on every host that takes backups. The attestation record is ordered by time, and signatures are checked against that order. doctor reports the drift it sees.

Client tools

A database backup runs the database's own dump tool on your host: pg_dump, mysqldump or mariadb-dump, or mongodump. Run safegrd doctor after you install or upgrade a client. It names the tool each surface will use.

"the newest pg_dump here is 15.8 (/usr/bin/pg_dump), older than the PostgreSQL 17 server"

Install a PostgreSQL client of the server's major version or newer. pg_dump refuses to dump a server newer than itself, and a newer pg_dump dumps older servers correctly.

On Debian and Ubuntu, add the PostgreSQL apt repository (apt.postgresql.org) and install postgresql-client-17. On macOS, run brew install libpq.

SafeGrd looks in your PATH, /usr/lib/postgresql/*/bin, /usr/pgsql-*/bin and Homebrew's libpq and postgresql@*, and picks the newest pg_dump it finds. To use one installed somewhere else, set SAFEGRD_PG_DUMP to its path.

$ safegrd doctor
Doctor
...
   [PASS] Surface shop connection        : opened shop on db:5432
...
   [FAIL] pg_dump for surface shop       : the newest pg_dump here is 15.19 (/usr/bin/pg_dump), older than the PostgreSQL 17 server; install the PostgreSQL 17 client (or newer), or set SAFEGRD_PG_DUMP
...
Error: 1 critical check failed
$ safegrd doctor
   [PASS] pg_dump for surface shop       : pg_dump 17.11 (/usr/bin/pg_dump) can dump this PostgreSQL 17 server
...
All critical checks passed.
A host with pg_dump 15 and a PostgreSQL 17 database. The first run exits 1. After installing postgresql-client-17 from the PostgreSQL apt repository, the second run exits 0. Recorded in Docker on 31 October 2026, with the CLI released on 25 October. The other checks are cut.

"no pg_dump found" or "no pg_dumpall beside ..."

Install the PostgreSQL client package. It includes both tools. SafeGrd reads the database's roles with pg_dumpall, and it uses the one in the same directory as the pg_dump it picked.

"no mysqldump or mariadb-dump found"

Install mysql-client for a MySQL server, or mariadb-client for MariaDB. You can also set SAFEGRD_MYSQLDUMP to the tool's path, and SAFEGRD_MYSQL to the client a restore uses.

"dumping a MariaDB server with mysqldump ..."

This is a warning, and the backup still runs. Install the client from the same project as the server. When both clients are installed, SafeGrd picks the matching one.

MySQL's mysqldump and MariaDB's mariadb-dump each write their own project's SQL best. A dump made with the other project's tool may need edits before the server restores it.

"no mongodump found"

Install the MongoDB Database Tools (mongodb-database-tools). They come in their own package, separate from the server and the shell. You can also set SAFEGRD_MONGODUMP to the tool's path. A restore needs mongorestore from the same package, or SAFEGRD_MONGORESTORE set to its path.

SafeGrd's server is unreachable

Backups keep running. The CLI prints a warning to stderr and writes the backup to your sink as usual. When the server answers again, the host sends its report.

Getting help

Include the output of safegrd version in any report. It prints the version, commit and build date. Attach the output of safegrd doctor --json too: it is the most useful thing you can send. File issues against the CLI at github.com/safegrd/cli.

For a problem in the console, open Help, click Copy diagnostics and paste the result into your email to support@safegrd.dev. It includes the console's address, the organization and plan, your role, the surfaces by kind, the browser, the time and the last five error notices from your session. It includes no token, key or password.