Skip to content
MetaTana

These docs are for MetaTana 2.0, coming soon

On this page

Scan Stuck Or Slow

A scan started but never finishes, runs for hours on a small library, or seems to hang at one step. A scan goes through six steps, and each can slow down for different reasons. This page walks them.

Common causes, in order of likelihood

  1. Provider rate limitsTMDb, TVDB, and others slow down callers that ask too often. MetaTana keeps within their published limits, but a first scan of a large library can spend a long time waiting.
  2. A slow network shareSMB and NFS shares are much slower than local disks. A scan reads every file and folder, so slow reads add up across thousands of files.
  3. Many hard files sent to AIWith AI Scrape new files and your own AI key (Pro), a scan asks AI about files it can't match by name. Many such files can slow it down. Background scans never spend hosted AI credits.
  4. One file failing again and againA damaged sidecar or an odd character in a file name can make one file fail repeatedly. Activity shows it under Show › Problems.
  5. Waiting behind running workA drop or Scan now waits for work that is already running, and Cancel works while it waits.
  6. Desktop background tasks stoppedScans, folder watching, Autopilot, and fetches run as background tasks in the desktop app. If they stop, nothing new starts. See below.
  7. Database not caught upRare. The scan looks finished in Activity, but Library doesn't update. It usually clears on its own; restarting MetaTana fixes it if not.

Diagnose

Watch Activity during the scan

Open Activity. Working now at the top lists the running scan, with what it is doing and how far it got. If the progress moves, the scan is working, only slowly. If it doesn't move, something has stalled.

A scan that hasn't started shows as Scan queue. If its folder can't be reached, the item says why, for example Library folder is offline: /Volumes/Media. The scan starts when the folder is available. The scan waits and starts on its own once the folder is back.

Where a scan spends its time

Step Why it can be slow
Finding files Slow reads (network share, USB drive, a very large folder tree)
Reading names Usually fast; slow here suggests another program is using the CPU
Local files Many NFO files to read; slow on network shares
Providers Rate limits, or a provider is down (check the provider's status page)
AI Many hard files sent to your own AI key
Saving Disk speed for the database; rarely the cause

Check for a file that keeps failing

In Activity, set Show to Problems. A file that fails again and again shows up there with the reason.

Check the providers

In Settings › Providers › Your keys, open the options next to each key. They show whether the provider is reachable, the last success and failure, and how fast it has been answering. A provider that keeps failing or answers slowly is the bottleneck.

Fix

  • Provider rate limit: wait. MetaTana paces its calls within the published limits, but a first scan of a large library takes time: up to an hour or two for 5,000 titles. On Pro, a scan waits out MetaTana's hosted metadata limit for as long as it lasts instead of sending titles to review. If the hosted service still doesn't answer, the title shows The provider didn't answer. The next scan tries again. The next scan matches it. If it shows TMDb rejected the API key. Check it in Settings, then scan again., your own TMDb key no longer works: paste a working one in Settings › Providers › Your keys and scan again.
  • Folder offline: connect the drive or share, then select Check again on its row on Folders. If it moved, use Reconnect folder… (see Move or restore a library). The waiting scan then starts.
  • Slow network share: check that the share is mounted with reasonable speed. For very large libraries on slow SMB, run MetaTana on the same machine as the storage, or accept the cost: the reading happens once per scan. Lowering METATANA_SCAN_CONCURRENCY can help a small NAS.
  • Too many files sent to AI: turn off AI Scrape new files in Settings › General › Matching for this scan, and turn it back on when you want it.
  • One failing file: open the failed Activity row, read the error, fix the file (rename, repair, or delete it), then scan again.
  • Database not caught up: quit MetaTana (or stop the container) and start it again.
  • A full drive: MetaTana's data drive is full. Free some space on it, then try again. means the drive with MetaTana's app data (Docker: the /app/data volume) has no room; The drive is full. Free some space on it, then try again. on a rename, NFO or artwork write means the library drive has none. Nothing was half written: the library database stays intact, a move that could not finish leaves the file where it was, and nothing is left behind on the full drive. Free some space, then retry.

Desktop: background tasks stopped

The desktop app restarts its background tasks (scans, folder watching, Autopilot, artwork and subtitle fetches, and backups) when they stop. The tray shows Restarting background tasks meanwhile. After three failed tries, the tray shows Background tasks stopped and a notice offers Restart. Inside the app, a banner across the top also says Background tasks stopped with a Restart MetaTana button. Select Restart or Restart MetaTana, or quit and reopen MetaTana. In a browser, for example with Docker, the same banner appears without the button; restart MetaTana to start the tasks again. If it keeps happening, send a report through MetaTana Support.

Incremental scans are much faster The slow one is the first scan, which has to identify everything from scratch. Later scans are incremental by default: they process files added or changed since the last scan, fill in technical details for files still missing them, and skip the rest. If scans stay slow, check that Incremental scan is on in Settings › General › Scanning. Rescan all files on a folder re-reads every file and is slower, so use it only when you need it, for example after editing NFO files by hand.

Going deeper