Troubleshooting
Resolve setup, recording, history, and hook failures.
Installation unavailable
The repository is private and the npm name unpublished as of November 9, 2026. Obtain source access or an owner-supplied artifact.
Configuration rejected
Inspect doctor --schema init.request or config.update.request. Initialization
requires a token and unique voice channel IDs and refuses to overwrite .env.
Use config update for existing homes. Check ownership, file type, permissions,
and --home rather than weakening credential checks.
Doctor fails or no recording starts
Read every check result. Verify executable FFmpeg/ffprobe, a valid token, guild
membership, and View Channel/Connect access. Confirm a human is in an allowed
channel. Only one channel is recorded; its grace and finalization must finish
before another can start. status reads local state without contacting Discord.
If the heartbeat is stale, the process may be running without making progress. Inspect logs
and verify that CLI and service use the same home.
Messages are absent
Text capture defaults off. Configure message channels, enable Message Content intent, grant permissions, and restart after updating configuration. Only new messages and edits are observed; no history or offline gaps are backfilled. Attachment binaries are not downloaded. History queries do not initialize an absent database.
Transcription is pending or failed
Check the configured executable and pending-file contract. A zero exit without
a valid atomically written result still fails. Pending/interrupted work resumes
on restart; failed work requires transcript retry. Enabling a hook does
not retroactively queue older recordings. Capture and PCM retention are independent
of transcription success.
Slash commands are missing or denied
Registration requires commands sync; startup does not register commands.
Preview with --dry-run, then sync and restart after configuration updates.
Discord integration permissions and the runtime user/channel allowlists both
apply. capabilities --live checks registration without mutations but does not
prove the daemon is online or a user has integration access. Removing config
blocks execution but does not delete stale Discord registrations.
Verification, export, or backup fails
Verification is read-only and does not repair artifacts or indexes. Preserve recovery data and inspect the check results. Destinations must be new absolute paths; existing files are not overwritten. A timeout can have an unknown outcome, so inspect the destination before repeating. Back up media separately from SQLite.