Skip to content

Troubleshooting

Common setup and runtime issues, and how to resolve them. If something here doesn't cover your problem, ask Trace, the support bot in the Engram Discord (post in the #ask-engram forum, mention @Trace, or run /bug), or open an issue. A diagnostics bundle makes it much easier to help. See Getting Help & Reporting Issues.

FFmpeg not detected (Windows)

Engram needs FFmpeg for episode matching (it extracts and decodes the audio that speech recognition transcribes). If the Config Wizard's Tools step shows "FFmpeg not found" even though you installed it, it's almost always because FFmpeg isn't on your PATH — not because of the version. Engram doesn't care which FFmpeg version you have; it only needs to be able to run it.

Work through these in order:

1. Confirm FFmpeg actually runs. Open a new PowerShell or Command Prompt window and run:

ffmpeg -version
  • If you see version output, FFmpeg is on your PATH — skip to step 2.
  • If you see "'ffmpeg' is not recognized…", FFmpeg is installed but not on your PATH. Go to step 3.

2. Restart Engram. A running program keeps the PATH it was launched with. If you installed FFmpeg (or edited your PATH) while Engram was open, fully close and reopen Engram so it sees the change, then click Re-scan in the Config Wizard.

3. Put FFmpeg where Engram can find it. Pick whichever is easiest:

  • Install with winget (recommended) and restart Engram:
winget install Gyan.FFmpeg

  • Add it to your PATH: extract your FFmpeg download, then add the ...\bin folder (the one containing ffmpeg.exe) to your system PATH via Settings → Edit the system environment variables → Environment Variables. Restart Engram afterward.

  • Drop it in a scanned location: copy ffmpeg.exe to C:\ffmpeg\bin\ffmpeg.exe. Engram scans this path (and the Chocolatey / scoop / winget install locations) automatically — no PATH change needed.

  • Point Engram at it directly: in the Config Wizard (or Settings → Tools), click Override path manually and enter the full path to ffmpeg.exe — for example C:\Users\You\Downloads\ffmpeg\bin\ffmpeg.exe. Enter the path to the .exe file itself, not the folder it lives in. The path is validated immediately and shows the detected version on success.

See Installing FFmpeg for download links.

FFmpeg on Linux / macOS

Install it with your package manager (sudo apt install ffmpeg, sudo dnf install ffmpeg, or brew install ffmpeg). See the Linux / macOS setup guide for details.

MakeMKV not detected

MakeMKV is required for disc ripping. If the Config Wizard can't find it, install it from makemkv.com and, if it still isn't detected, use Override path manually to point at makemkvcon64.exe (typically under C:\Program Files (x86)\MakeMKV\). On Linux, see Linux / macOS setup. Don't forget to enter your MakeMKV license key in the wizard.

TMDB token not working

The TMDB field expects a Read Access Token (v4 auth) — the long string starting with eyJ… — not the shorter v3 "API Key". The wizard validates it as you type. See Configuration for where to find it.

Discord notifications aren't arriving

Engram posts to a Discord webhook when a disc completes, fails, or parks waiting for you. Settings live under Settings, Preferences, Notifications.

First, prove the webhook works. Click Send test message. It tests the webhook you have saved, so if you just pasted a new URL, save before testing. A sample notification should appear in the channel within a second or two. If it doesn't:

  • Read the message next to the button. A red cross means Discord refused the post, which usually means the webhook or its channel was deleted: re-create it under Channel Settings, Integrations, Webhooks and paste the fresh URL. An amber warning means the check itself could not run, so the webhook may well be fine and the problem is between your browser and Engram.
  • Check that the URL starts with https://discord.com/api/webhooks/.

The test works but real discs are silent. Check the three per-event toggles. Each event has its own switch, so it's possible to have completions enabled and review notifications turned off, or the reverse.

Notifications arrive but don't alert my phone. Discord does not push notifications for embed content. Set Review Mention to your user ID (<@123456789012345678>), a role (<@&987654321098765432>), or @here. That value is sent as the message body, which is the part Discord actually pings on. To find your user ID, enable Developer Mode in Discord's Advanced settings, then right-click your name and choose Copy User ID.

Notifications aren't clickable. Set Dashboard URL to the address you use to reach Engram from other devices, for example http://192.168.1.50:5173. Notifications then link straight to the job. Leave it blank and notifications still arrive, just without a link.

Every disc in my box set looks the same. Each notification carries a Disc field built from the disc's volume label plus its disc number, so THE_WIRE_S1 (Disc 3) is distinct from disc 4. If the field shows only Disc 1, the disc reported no volume label and Engram has no better identity to use; naming the disc during identification fixes it for that job.

A track says its only audio is another language

Engram identifies TV episodes by listening to the dialogue and comparing it with English subtitles. When every audio track in a ripped file is another language (an anime disc without an English dub, or a foreign-language bonus episode), Engram does not guess: the track goes to review with a note naming the language, and you assign the episode by hand.

The note says the disc also has English audio. MakeMKV only rips the audio tracks its language settings select, so an English dub on the disc can be missing from the file. In MakeMKV, open Preferences > Language (or adjust the default track selection), add English, and re-rip the track.

On a disc with several audio tracks, Engram always listens to the English one, whichever track the disc marks as the default.

Restoring the database after an upgrade

Engram's database (engram.db) holds your settings and API keys (MakeMKV key, TMDB token, AI and OpenSubtitles keys) along with your job history. Each time Engram starts on a new version, or finds that the database's layout needs updating, it first saves a copy of the database next to it, named engram.db.bak-<previous-version>-<timestamp> (for example engram.db.bak-0.41.0-20261020T153012.123456Z). The first upgrade to a version with this feature names the copy bak-unknown, because no earlier version was recorded. Only the three newest copies are kept. The startup log says when a copy is made: Backed up database to ... before migrating.

Where the database lives:

Install Database
Packaged app (Windows, Linux, macOS) ~/.engram/engram.db (on Windows, C:\Users\<you>\.engram\engram.db)
Docker /config/.engram/engram.db inside the /config volume
From source backend/engram.db (or wherever DATABASE_URL points)

If an upgrade leaves Engram unable to start, or your settings look wrong afterwards, restore the copy:

  1. Stop Engram completely (quit the app, or stop your Engram container, for example docker compose stop engram).
  2. In the database folder, move engram.db aside, along with engram.db-wal and engram.db-shm if they exist. Keep them until you're sure the restore worked.
  3. Copy the backup you want (usually the newest) to engram.db.
  4. Delete engram.db.version so the next start treats the database as coming from the older version.
  5. Start the version of Engram that made the backup (the version is in its name). Starting a newer version will try the same upgrade again, so if the upgrade itself is the problem, stay on the older version and report it with the startup log.

If a backup can't be written (for example, the disk is full), Engram logs a warning and starts anyway.

Diagnostics bundle

When reporting a problem, attach a diagnostics bundle so the logs and environment come with it. From the dashboard, open a job's detail view and download its diagnostic .zip, or fetch the overall report from GET /api/diagnostics/report. Secrets (API keys, tokens) are redacted automatically.

In Discord, drop the .zip into your thread with Trace: it reads the versions, job state and log errors for you, and attaches a summary to the GitHub issue when your report is filed. See Attaching a diagnostics bundle.