Skip to content
MetaTana

These docs are for MetaTana 2.0, coming soon

On this page

Troubleshooting

Start with the symptom. Each page below opens with a short "what you see" description, walks the checks in order of likelihood, and gives a fix for each one.

Pick a symptom

Install and sign-in The sign-in code never arrives, the TMDb key test fails, macOS, Windows, or Linux blocks the app, or Docker cannot see your media folder.
Diagnose →
UI looks stale or doesn't update The app shows old data, missing recent edits, or refuses to reflect changes you just made.
Diagnose →
Scan found too few files A folder with many media files turned into far fewer titles in the library, or none.
Diagnose →
Scan is stuck or very slow A scan started but never finishes, runs for hours, or seems to hang at one step. On desktop, the tray or a banner says Background tasks stopped.
Diagnose →
Wrong identity match The right file got the wrong title, year, or episode number, or a title says it couldn't reach a metadata provider.
Diagnose →
Rescrape keeps a bad value Your manual edit got overwritten on the next refresh or rescrape. Or the same wrong value keeps coming back.
Diagnose →
Sidecar didn't appear on disk MetaTana shows the metadata, but no NFO or artwork file landed next to your media.
Diagnose →
Artwork not loading A slot is empty after a fetch, an image is broken, or the same wrong artwork keeps coming back.
Diagnose →
Hosted feature fails Skyhook, AI Vision, MCP bridge, or the local API key throws an authentication or credit error.
Diagnose →
Playback client can't see files Plex, Jellyfin, Kodi, or Emby don't show titles MetaTana wrote, or show them with old metadata.
Diagnose →
Restore is waiting You scheduled a database restore and restarted, but Settings › Maintenance › Backups still says the restore is waiting.
Diagnose →
Migration from another app is stuck Imported folders have wrong paths, the import never finished, or NFOs aren't being read.
Diagnose →

General checks before sending a report

Whatever the symptom, these three checks rule out the most common causes:

  1. Open Activity and read the most recent entriesMost "did it work?" questions are answered there. Each entry says what MetaTana decided, which files it changed, and why something failed, in plain text. Show › Problems lists only what failed.
  2. Confirm which data folder is in useThe desktop app shows its data and logs folders under Settings › Maintenance › Data & diagnostics. If you've moved your library between computers or Docker volumes, the app might be reading a different database than the one with your recent work. In Docker, the data folder is whatever you mounted at /app/data.
  3. Make sure only one copy of MetaTana is runningTwo copies (for example the desktop app plus a Docker container on the same port) can show stale pages or write to different databases. Quit extra copies. Advanced: lsof -i :3000 on macOS/Linux, or Task Manager on Windows, shows what is using the port.

The app shows an error screen

If a page fails, MetaTana shows Something went wrong with Try again and Send a report. The error itself is under Details, and Copy details copies the error and its ID so you can paste them into a report. In the desktop app, Open logs opens the logs folder.

Need to share a report?

In the app, open Help in the sidebar and select Send a report. Choose Bug, Question, or Idea, and fill in a Short title and Details; Steps, Expected, Impact, and Frequency help us sort the queue. Include app details shows what it adds, such as the app version and platform, before you send. The form never sends logs, file paths, Activity data, screenshots, or attachments. Sending from the app needs you to be signed in. Your reports on Help lists your reports and their replies. In the desktop app, Help › Report a Problem... in the menu bar opens it too, and Send a report on an app error page opens the same form with the error filled in.

Can't open the app? Use the same private form on the website at MetaTana Support.

You can preview and include an error code or request ID that you type yourself. The form does not upload screenshots, files, logs, browser details, or Activity diagnostics. An unfinished draft stays in the tab so a reload doesn't lose it: up to 7 days in the app, and up to two hours on the website form.

Signed-in reports appear in My Reports. Guests receive a private reference and status link. The private detail page shows customer-safe progress, replies, and release availability, and lets you reply or change which email updates you receive. Keep a guest status link private because it grants access to that report.

If you deliberately want a public technical report, use the public support issue form only after removing email addresses, file paths, logs, keys, and all other private data. Send security problems through private vulnerability reporting, never a public issue or normal bug report.

Export report in Activity's ⋯ menu writes a separate JSON file of recent Activity, diagnostics, and background work, with secret-looking values and full local paths masked. It is never attached to a report automatically. Copy diagnostics in Settings › Maintenance › Data & diagnostics copies a short summary (version, platform, database state) instead.

Review before you share Masking can miss values. Skim the exported file for hosted session tokens, provider secrets, or local paths you'd rather not publish before pasting it into a public issue.

Going deeper

  • Library health: the disk checks behind many of these symptoms
  • Reference: file layout: where the database, backups, sidecars, and trash actually live on disk
  • Recipes: task-oriented walkthroughs that prevent some symptoms in the first place