Skip to content
On this page

Install And Sign-In Problems

Start here if MetaTana will not open, will not sign you in, will not accept your TMDb key, or cannot see your media folder.

421 Misdirected Request on your own domain

What you see: opening MetaTana through a domain name, for example https://metatana.example.com behind a reverse proxy or Cloudflare Tunnel, shows 421 Misdirected Request and a message like MetaTana was opened as "metatana.example.com", which is not on its list of allowed host names. Opening it by IP address still works.

Why: MetaTana answers only on names it can trust, so another website cannot reach it through your browser. IP addresses, localhost, one-word names such as nas, and names ending in .local, .lan, .home, .home.arpa, .internal, or .localdomain always work. Other names must be listed.

  1. Add the name the message showsSet METATANA_ALLOWED_HOSTS to that exact name. Compose: - METATANA_ALLOWED_HOSTS=metatana.example.com under environment:. docker run: -e METATANA_ALLOWED_HOSTS=metatana.example.com. Unraid: add a Variable with that key. TrueNAS: Additional Environment Variables.
  2. Several namesSeparate them with commas: metatana.example.com,nas.tail1234.ts.net. Use host names only, without https:// or a path.
  3. Recreate the containerRun docker compose up -d, or apply the change in Unraid or TrueNAS. A plain restart does not pick up a new Compose value.

*.example.com allows every subdomain of a domain you own. Do not use a wildcard for shared domains such as *.ts.net or a dynamic-DNS domain, and avoid *, which turns the check off. More detail: Your Own Domain Or Reverse Proxy.

On Synology, QNAP and ASUSTOR packages, open MetaTana by the NAS's IP address or its .local name (for example http://nas.local:3000). Opening it through your own domain name isn't supported in these packages yet.

Pages load, but sign-in fails with 403

What you see: the page loads through your proxy, but signing in or saving a change fails with 403 and a message that starts MetaTana only accepts changes from its own pages.

Your reverse proxy is replacing the browser's Host header, and the name you opened MetaTana with is not allowed. When the proxy rewrites Host, MetaTana accepts a change only when the browser marks it as coming from the same page origin and that name is an IP address, a local name such as nas.local, or listed in METATANA_ALLOWED_HOSTS. Fix it either way:

  • Pass the original Host (recommended). Plain nginx: add proxy_set_header Host $http_host;. Apache: add ProxyPreserveHost On. Cloudflare Tunnel: leave HTTP Host Header empty. Nginx Proxy Manager, SWAG, Traefik, and Caddy pass it by default.
  • Allow the name. Add the domain you open MetaTana with to METATANA_ALLOWED_HOSTS and restart MetaTana. You need this for your own domain anyway.

A 403 page from a proxy, firewall, or web filter in front of MetaTana's account service never signs you out. MetaTana keeps you signed in and works in cached or offline mode until it can check your account again.

This MetaTana is linked to a different account

What you see: after you sign in, MetaTana shows This MetaTana is linked to a different account. with a Sign out button instead of the library.

Why: each install belongs to the first MetaTana account that signed in to it. Other accounts cannot open it. This also shows when someone signs in with another account in a browser where the owner signed out: signing out ends that browser's session on the install, so the next account can't open the owner's library.

  1. Use the owner's accountSelect Sign out, then sign in with the email of the account that set up this MetaTana. In a household that shares one install, everyone signs in with that account.
  2. Or change the owner from the machineIf you are the person who runs this install and want a different account linked (for example after deleting the old one), run metatana owner reset on the machine that runs MetaTana. Docker: docker exec metatana metatana owner reset (use your container name from docker ps). Unraid: Docker › MetaTana › Console, then metatana owner reset.
  3. Sign in againThe next account to sign in and enter the new claim code that reset prints becomes the owner, even while the install still holds the old owner's session for background work. Run metatana owner status to check whether an account is linked.

Signing out and deleting an account do not unlink the install. Only the reset above does, or a factory reset.

Enter the claim code

What you see: after you sign in to a Docker or NAS install that has no owner yet, MetaTana shows Enter the claim code instead of the library.

Why: the first account to claim an install from another device must prove it can see the server. Until an account is linked, MetaTana prints a one-time code such as ABCD-EFGH to the server log every time it starts. The desktop app never asks, and neither does an install that already has an owner.

  1. Find the codeDocker: docker logs metatana, or docker exec metatana metatana owner claim-code (use your container name from docker ps). Unraid: Docker › MetaTana › Logs, or metatana owner claim-code from the container Console. TrueNAS: Apps › MetaTana › Logs, or sudo docker exec <container> metatana owner claim-code from System › Shell. Synology: Container Manager › Container › MetaTana › Log. QNAP: Container Station › Containers › metatana › Logs. ASUSTOR: open the MetaTana container's log in Portainer.
  2. Enter itType the code and select Link this MetaTana. Your account becomes the owner.
  3. If it says the code does not matchCopy the code again from the newest log lines or from metatana owner claim-code. After metatana owner reset or a factory reset, the old code no longer works. Each account gets 10 tries every 15 minutes; after that, wait and try again.

If sign-in instead says Could not verify your MetaTana account. Try again., MetaTana could not reach the hosted service to check which account set up this install. Wait a moment and try again; see the reachability check under Sign-in code not arriving.

Sign-in code not arriving

What you see: you selected Send code, but no email arrives, or the app says MetaTana could not send a sign-in code right now. Try again in a moment.

  1. Wait a minute, then check spamLook in spam, junk, promotions, or any quarantine your mail provider uses. Search for MetaTana.
  2. Check the address, then resendIf the address has a typo, select Use a different email and fix it. Otherwise select Resend code on the code step to get a new code for the same address.
  3. Use the newest code, within 10 minutesIf you sent more than one, enter the code from the latest email. Codes expire after 10 minutes.
  4. Slow down if you retried many timesEach email address can request only a few codes per hour. The app tells you how long to wait.
  5. Check that MetaTana can reach the hosted APIRun curl -s -o /dev/null -w "%{http_code}\n" https://api.metatana.com/health from the same machine or container. Anything other than 200 points to a firewall, VPN, or proxy.

Sign-in error messages

The sign-in screen names the problem:

Message What to do
That code expired. Choose Resend code to get a new one. Select Resend code and enter the new code within 10 minutes.
Too many incorrect codes. Choose Resend code to get a new one. That code is used up. Select Resend code and enter the newest code.
Too many sign-in codes requested. Try again in … or Too many attempts. Try again in … Wait the time shown, then try again. Retrying sooner fails the same way.
That code was not valid. Check the newest email and try again. Check for a typo, and use the code from the most recent email.
Can't reach your MetaTana account. Check your connection and try again. Your device can't reach MetaTana's account service. See the reachability check above.
MetaTana can't send sign-in emails right now. Try again later, or link this device instead. Sign-in email is down on MetaTana's side. Try later, or link this device as described below.

If email is blocked where MetaTana runs, select Link this device instead on the sign-in screen: select Get a code, then claim it at metatana.com/link from a browser where you are already signed in.

TMDb key not accepted

The Add a free TMDb key dialog checks the value with TMDb as soon as you paste it and saves it only when TMDb accepts it. Open it from a drop's page (Get a free TMDb key), the Library card (Add a free TMDb key (2 minutes)), Home (Improve matches), or Settings › Providers › More › Key setup (Add TMDb key step by step).

If the check fails, the dialog says why in one sentence:

  • TMDb did not accept that value. Copy the API Key or the API Read Access Token again from TMDb's API settings page. Make sure no spaces or line breaks came along.
  • TMDb is busy right now. or TMDb is having trouble right now. Wait a few minutes and paste again.
  • MetaTana could not reach TMDb. Check firewall, VPN, or proxy rules for api.themoviedb.org.

A rejected value is never saved, so a key that already works stays in place. No key yet? The dialog's first two steps link to TMDb sign-up and API settings. The full walkthrough is in API keys: guided TMDb key setup.

If a TMDB_API_KEY environment variable (common in Docker setups) holds a bad key, fix the variable and restart the container.

Pro accounts can skip this step: hosted metadata needs no personal key.

macOS: the app will not open

  • First-open prompt: macOS asks whether you want to open an app downloaded from the internet. Select Open. This is expected once.
  • Intel Mac: the desktop build is for Apple silicon only, so macOS will not run it on an Intel Mac. Use Docker instead.
  • "Damaged" or "can't be verified": the download is usually incomplete or was changed. Delete it, download the DMG again from Desktop installation, and drag MetaTana into Applications before opening it. Do not disable Gatekeeper; if the warning persists, contact support.

Windows: SmartScreen warning

The Windows installers are signed, but SmartScreen can still show Windows protected your PC for a new release. Select More info and confirm that a publisher is listed before selecting Run anyway. If no publisher is shown, do not run it: download the installer again from Desktop installation.

Linux: AppImage will not start (FUSE)

What you see: an error such as AppImages require FUSE to run or libfuse.so.2: cannot open shared object file.

  • Install FUSE 2. On Debian or Ubuntu: sudo apt install libfuse2 (Ubuntu 24.04 and later: sudo apt install libfuse2t64).
  • Or run it without FUSE: ./metatana-linux-x86_64.AppImage --appimage-extract-and-run (use your file name).
  • Or use the Linux install script. It prefers a native package and creates an extract-and-run wrapper when FUSE is unavailable.
  • Make sure the file is executable: chmod +x metatana-linux-*.AppImage.

Docker dashboard shows MetaTana offline after an update

Open MetaTana directly and check /api/health at the same address. For a dashboard such as Glance, use the health URL that the dashboard container can reach. A successful health check means the web server is answering. Open Library to check that your titles are accessible too.

If both are unavailable, check the container logs. In split Docker, check the web and background containers separately. If the container restarts over and over and its log says Runtime lease denied, update to MetaTana 2.3.2 or later. Version 2.3.1 and earlier could not start over the lock that a killed container or a power cut left behind. After such a stop, 2.3.2 takes up to a minute at startup to check that the previous MetaTana has stopped, then starts.

If the logs repeatedly mention a database lock after replacing a container, follow the offline recovery steps. Restarting the container over and over can interrupt a library upgrade.

Docker folder not visible or permission denied

What you see: the folder browser says Path does not exist: … or Permission denied: …, or a file change such as organize or an NFO write reports Library folder is not writable: … Fix folder access, then retry.

  1. Use the container pathEnter the path inside the container, such as /media or /media/Movies, not the host path (/mnt/…).
  2. Check the mountConfirm the media folder is mapped into the container, for example /path/to/media:/media in Compose, a Path on Unraid, or Media Storage as a Host Path on TrueNAS. Recreate the container after changing mounts.
  3. Check the userMetaTana reads media as the user set by PUID/PGID (default 1001; 99/100 on Unraid; 568 on TrueNAS). That user needs read access to scan. Test it with docker compose exec -u 1001:1001 metatana ls -la /media (use your IDs).
  4. Writes need a read/write mountLibrary folder is not writable on a :ro mount is expected. Remove :ro only when you want NFO, artwork, rename, organize, or delete. A :ro folder scans normally and Folders shows Read only with "Scans work, file changes are blocked"; only file changes report this message.

Do not fix permissions with chmod 777. Give the MetaTana user or group the access it needs instead.

Going deeper