Troubleshooting

Start with the process boundary, selected database, credential audience, and active application identity. Do not work around a failure by widening a role or editing a redb file.

Service does not start

systemctl --user status riffdbd.service
journalctl --user -u riffdbd.service --since today

Common causes are a missing protected digest-key file, incorrect permissions, duplicate database aliases, a redb path that is not writable by the service user, or startup integrity validation rejecting incomplete durable evidence. Correct configuration or restore from a verified backup; do not delete records inside the database.

An orderly stop normally permits bounded validation on the next start. A forced kill, incomplete drain, storage repair, restore, migration, or invalid clean-close lifecycle record instead selects complete validation automatically. This can make one restart materially slower without indicating a startup deadline failure. Do not remove or modify private metadata to force either path. See Startup Integrity and Clean Restarts.

If stderr reports RDB-FORMAT-0101, keep the service stopped and inspect the same immutable decision explicitly:

riffdb storage preflight --database-path /absolute/path/to/riffdb.redb

Follow only the returned action. A declared same-epoch transition uses riffdb storage upgrade with the exact verified source backup; an unsupported epoch requires the retained source binary and the documented symbolic export/reimport ceremony. Never remove the marker or upgrade receipt, copy a marker from another database, or look for a force/reset flag.

If a restart reports corruption only when a particular record is used, that is the documented accessed-row integrity boundary, not evidence that validation was disabled. Keep the service stopped if the error affects required authority or active application state, retain the incident ID, and restore from a verified backup when directed. To check the whole database, run riffdb storage scrub and observe the printed operation with riffdb backup operation; it takes the database offline for the pass. Do not edit lifecycle metadata or invoke internal storage APIs as a substitute.

Health reports degraded with a failed storage scrub

The background scrub found a row that fails validation. The storage_scrub member is failed with an incident ID, and authoritative_storage is degraded. Service continues, and any request that touches the damaged row fails closed. Retain the incident ID, avoid the affected data where possible, and restore from a verified backup when directed. A restart does not clear the defect: the next background scrub starts at pending and finds it again. On a V2 database a failure in retained history withdraws authoritative readiness instead; the server then reports not_ready. See Startup Integrity.

CLI connects to the wrong database

Inspect the client configuration and its database alias. Authenticated health and active-contract responses include the selected alias and audience. An unknown alias or a credential issued for another database fails closed.

See Configuration and Multiple Databases.

MCP starts but tools are missing

riffdb-mcp doctor --config ~/.config/riffdb/mcp-myapp.toml

Then check:

1. The MCP host restarted or reloaded after configuration changed.
2. Tool names contain only lowercase letters, digits, and underscores.
3. The bridge selects the intended database alias.
4. The credential is the bound application role, not a bootstrap credential.
5. The active contract and query module match the generated application lock.

tools/list is capability-filtered. A missing operation can be absent, stale, or unauthorized; the server deliberately does not disclose which to an untrusted caller.

Application check reports stale artifacts

Run the explicit sequence from the application repository:

riffdb application check
riffdb application lock --write
riffdb application generate --locked
riffdb application lock --check

Review the lock and generated diff. Do not edit generated files. A successor must compile against the exact active parent; all local role and query preflight must succeed before deployment performs its first remote mutation.

A command response was interrupted

Do not invent a new idempotency key. Retry the identical command with its original key or use the client facade’s outcome resolution. A changed input under the same key is rejected; a new key denotes a new logical command.

Contract deployment fails

Read the structured source-spanned diagnostic. Additive evolution is bounded: renames, removals, type changes, and other incompatible edits require the documented pre-alpha reset path for disposable data. Back up the database before reset and stop the service throughout the operation.

Projection is behind

Inspect health and the reported projection frontier. A read-after-commit query may wait only to its bounded deadline. Projection state is rebuildable; never patch it to make a frontier appear current.

Report a defect

Capture the RiffDB version, public error code, incident ID, database alias, operation name, relevant configuration with secrets removed, and a minimal reproduction. Never attach credential files, digest keys, raw protected logs, or production database files.