Skip to content
MetaTana

These docs are for MetaTana 2.0, coming soon

On this page

Hosted Feature Fails

Skyhook, AI Vision, the MCP bridge, and the local API key all depend on your MetaTana account. When one fails with a sign-in error, a credit error, or a "Pro required" message, the cause is usually one of these: not signed in, signed in to the wrong account, no Pro plan, no credits left, or MetaTana's hosted service can't be reached. This page walks them.

Common causes, in order of likelihood

  1. Not signed inYour sign-in expired or never finished. Some hosted features refuse quietly instead of showing an error.
  2. No ProYou're signed in, but the feature you used (API key, MCP, hosted metadata, AI Vision) needs Pro and the account is on Free.
  3. No credits leftAI Vision and some hosted calls spend credits. When the balance reaches zero, the feature returns a credit error.
  4. Hosted AI temporarily unavailableThe app reached MetaTana, but the hosted AI model service could not complete the request. Failed model calls are refunded; retry shortly.
  5. Hosted API unreachableThe MetaTana app can't reach api.metatana.com. Common on offline or locked-down networks. The app shows Can't reach your MetaTana account. Pro features are paused; your local library still works. and keeps you signed in.
  6. A provider is turned offA metadata provider is switched off in Provider availability, so neither hosted nor local lookups use it.

Diagnose

Check sign-in state

Open Settings › Account. It shows your email and plan. If you aren't signed in, sign in. If it shows a different email than you expected, you're on the wrong account. If it shows Offline, you are still signed in but MetaTana can't be reached right now; see the reachability check below.

Check your Pro plan

Same screen. Plan shows MetaTana Pro or MetaTana Free, with a note when a payment failed. On Free, or when the payment failed, Pro features refuse.

Check your credits (AI Vision and other hosted AI)

Open Settings › Account › Credits to see how many AI credits you have left.

Check hosted API reachability

curl -s -o /dev/null -w "%{http_code}\n" https://api.metatana.com/health

Should return 200. Anything else (timeout, connection refused, 5xx) means the hosted API can't be reached from your network. Check firewall, VPN, or proxy.

For Docker installs, sign-in and Link this device instead work from whichever address you open MetaTana at: localhost, a LAN IP, a local name, or your own domain behind a reverse proxy (listed in METATANA_ALLOWED_HOSTS). After you sign in, MetaTana opens normally; the Unlock this server screen belongs only to the very first setup. If you open the Docker install beyond your LAN, keep it behind TLS and an access layer you control; MetaTana can change your library files and should not be left open to the internet.

Check the specific feature's error in Activity

Open Activity and set Show to Problems, or search for the title. The failed row says in plain words what failed and what to do next. ⋯ › Export report saves the details for a support report.

Fix

  • Not signed in: restart MetaTana or reload the page. At Sign in to MetaTana, enter your email, select Send code, then enter the six-digit code and select Verify and continue. If the code does not arrive, see Install and sign-in problems.
  • Wrong account: sign out in Settings › Account › Sign-in & devices, then sign in with the right email.
  • No Pro: upgrade from Plan in Settings › Account. The app picks up the new plan within a few minutes.
  • No credits left: buy a credit pack in Settings › Account › Credits. Packs are one-off and work only while Pro is active. A bulk AI Scrape stops at the first out-of-credits answer instead of trying every remaining title; add credits, then run it again.
  • Hosted AI temporarily unavailable: retry shortly. You don't need your own key for hosted AI Vision. MetaTana never switches to your own AI key by itself, because one identify could then be paid twice. Rescrape asks instead: select Try again to retry hosted AI, or Use my own key to run this identify with the AI provider key you set up.
  • Hosted API unreachable: check that this computer can reach api.metatana.com on port 443. You don't need to sign in again: once MetaTana is reachable, Pro features resume. The app checks again when you return to its window or your connection comes back. Only a session MetaTana rejects as invalid signs you out.
  • Company network that inspects HTTPS: the desktop app trusts certificates installed on your computer. Install your company's root certificate in the system store (Keychain Access on macOS, the Windows certificate store, or your Linux distribution's CA store), then restart MetaTana. NODE_EXTRA_CA_CERTS does not apply to the desktop app. On Docker, set NODE_EXTRA_CA_CERTS in the container environment.
  • Provider turned off: open Settings › Providers › More › Provider availability and turn the provider back on. If lookups still fail, the provider may be down for a while; check api.metatana.com/health and Home's problem list.
Your own keys keep metadata working Skyhook fetches metadata for Pro accounts, but most providers also take your own key in Settings › Providers › Your keys. With your own TMDb key, MetaTana keeps matching while hosted metadata is unreachable. Useful on offline networks or when the hosted service is having trouble.

Going deeper