Troubleshooting
Start with these three commands. They answer most questions before you need to read a log.
| Command | What it tells you |
|---|---|
| safegrd doctor | Checks 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 validate | Checks config syntax, permissions and surface definitions without running anything. |
| safegrd daemon status | For each surface: what is due, what is failing, and when it last succeeded. |
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:
credential_held: truebecomescredential: {from: safegrd}.database_url_envandpassword_envbecomecredential: {from: env, name: VARIABLE}.credential_commandbecomescredential: {from: command, run: "..."}.
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.
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.