Troubleshooting
Three commands answer most questions before you have to read a log.
| Command | What it tells you |
|---|---|
| safegrd doctor | Deep preflight: config permissions, keypair integrity, sink reachability and real Object Lock support, control plane reachability, host clock skew, and whether every configured surface opens with the credential its backup will use. On an enrolled host the result shows in the console. --json for CI. |
| safegrd status | The quick check: connectivity, storage immutability, encryption keys. |
| safegrd config validate | Config syntax, permissions and surface definitions, without running anything. |
| safegrd daemon status | Per-surface state: what is due, what is failing, when each last succeeded. |
Common failures
"Bucket does not support Object Lock"
Object Lock must be enabled at bucket creation on most providers and cannot
be turned on afterwards. Create a new bucket with it enabled and versioning on. If
the provider has no Object Lock at all, as with DigitalOcean Spaces, 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
Values must be specified in exact uppercase: COMPLIANCE,
GOVERNANCE, or NONE. Strict parsing prevents
accidental misconfiguration of retention guarantees.
"credential_held is no longer read"
The config was written for an older CLI. A surface now says where its credential comes from
in one credential block, and the message names the replacement:
credential_held: true becomes credential: {from: safegrd};
database_url_env and password_env become
credential: {from: env, name: VARIABLE}; credential_command becomes
credential: {from: command, run: "..."}. See Configuration.
Config permissions rejected
chmod 600 ~/.safegrd/config.yaml. It holds connection strings, so this
is enforced rather than warned about on POSIX hosts.
Restore cannot find a key
The private key resolves from key_path, from
SAFEGRD_PRIVATE_KEY, or from --key-path /
--private-key. It is never in config.yaml by design. On a
recovery host, copy the key file across and point --key-path at it.
My snapshots vanished
Under Object Lock they almost certainly did not. A DELETE writes a
delete marker that hides them. Run safegrd undelete --all, and see
Storage and retention.
IMAP certificate errors on a self-hosted server
Give the surface the internal CA bundle as ca_file, or a one-off backup
--email-ca-file, or set SAFEGRD_EMAIL_CA_FILE. Certificate checks
cannot be turned off.
Clock skew warnings
The attestation chain is time-ordered and signatures are checked against it. Run NTP
on any host taking backups; doctor reports the drift it sees.
The control plane is unreachable
Backups continue normally. The CLI logs a reporting warning to stderr while continuing to protect surfaces and write to your storage sink. Snapshots remain secure in storage, and attestation logs sync once connectivity is restored.
Getting help
safegrd version prints the version, commit and build date; include it
in any report. safegrd doctor --json output is the single most useful
attachment. Issues against the CLI belong at
github.com/safegrd/cli.