Skip to Content
FAQ

Frequently Asked Questions

General

Installation

Troubleshooting

Data & Maintenance Jobs

General

What media servers does Tracearr support?

Tracearr supports Plex, Jellyfin, and Emby. You can monitor multiple servers of different types from a single Tracearr instance.

Is Tracearr free?

Yes, Tracearr is free and open source under the AGPL-3.0 license.

Can I import data from Tautulli or Jellystat?

Yes. Tracearr imports from Tautulli (Plex), directly from the Playback Reporting plugin (Jellyfin and Emby), and from a Jellystat backup file. See the import guide.

Does Tracearr need a mail provider?

No. Tracearr speaks SMTP and nothing else, so any relay works, including one running on the same machine as Tracearr. The seven provider presets are there to save you looking up a host and a port; Custom takes whatever you have. See Email & Newsletters.

Is a contact email the same as a login email?

No, they are two different fields on two different things. A Tracearr account’s email is part of signing in and is what the set-email recovery command changes. A contact email is an address the owner types for a person so newsletters have somewhere to go. It grants no login, and it is never used to match a synced media server account to a Tracearr account.

Installation

What are the system requirements?

  • Docker and Docker Compose (recommended)
  • 1GB RAM minimum (2GB recommended)
  • PostgreSQL with the TimescaleDB extension for the database
  • Redis for caching

Can I run Tracearr without Docker?

Yes, on Proxmox. The community helper script , which we maintain, installs Tracearr, PostgreSQL with TimescaleDB, and Redis into an LXC container with no Docker involved. That is the only non-Docker install we support. See Upgrading for how to update it.

Anything else (bare metal, your own VM, a distro package) is on you. There is no written guide and we don’t recommend it. The pieces are all in the repo if you want to work it out: docker/Dockerfile shows how the app is built with pnpm and started (node apps/server/dist/index.js on Node 22 or newer), docker/docker-compose.dev.yml shows the services it expects next to it, and docker/Dockerfile.supervised installs all three on one Debian image, which is as close to a manual install as the repo gets. The Proxmox script is worth reading for the same reason, since it puts the same stack onto a plain OS without containers.

The database is where this gets hard. Tracearr needs PostgreSQL with the TimescaleDB and timescaledb_toolkit extensions loaded and pg_trgm available, plus Redis. A plain PostgreSQL install does not work: the migrations create hypertables, continuous aggregates, and compression and retention policies, and they fail on the first run without TimescaleDB. PostgreSQL also has to run with settings Tracearr depends on. Read them off the command: line in docker-compose.pg18.yml, in particular max_locks_per_transaction=4096 and max_connections=150, along with 512MB of shared memory. Leave those at stock values and a large Tautulli import runs out of lock table space.

If you go that route, you are on your own. We can’t help with problems that only show up outside the images and the Proxmox script.

Troubleshooting

Tracearr can’t connect to my media server

  1. Verify your server URL is correct and accessible from Tracearr
  2. Check that your API key/token is valid
  3. Ensure there are no firewall rules blocking the connection
  4. Check the Tracearr logs for specific error messages
  5. Try Disabling IPv6 in Docker

Jellyfin 12: Tracearr can’t connect after upgrading Jellyfin

Jellyfin 12 disables legacy authorization by default, which rejects the older X-Emby-Authorization and X-Emby-Token headers that earlier Tracearr versions used to authenticate. A previously working Jellyfin server can start failing right after you upgrade it to 12.

Upgrade Tracearr to 1.4.29 or newer. From 1.4.29 on, Tracearr uses the standard Authorization header that Jellyfin 12 expects, and it stays compatible with Jellyfin 10.11 — so you can upgrade Tracearr before or after Jellyfin.

You don’t need to regenerate your API key. Regenerating it won’t help on an older Tracearr version, and isn’t necessary once you’re on 1.4.29+.

Jellyfin 10.11.9+: Playback Reporting check fails with a 500 error

Check Plugin on the Import page reports that Playback Reporting isn’t installed and shows jellyfin request failed: 500 Internal Server Error, even though the plugin is installed and its own reports load fine. The Jellyfin log has a matching entry for POST /user_usage_stats/submit_custom_query:

System.MissingMethodException: Method not found: 'System.Collections.Generic.IEnumerable`1<...User> MediaBrowser.Controller.Library.IUserManager.get_Users()'.

Jellyfin 10.11.9 removed the IUserManager.Users API that Playback Reporting version 17 calls. The plugin’s submit_custom_query endpoint, the one Tracearr imports through, now fails before it runs. The plugin project fixed this the day after 10.11.9 shipped, but published the fixed build under the same version number, 17.0.0.0. Jellyfin’s plugin updater only offers versions newer than the one installed, so any install from before May 22, 2026 keeps the broken build and still shows as up to date in the plugin catalog.

Uninstall and reinstall the plugin to pull the fixed build:

  1. In Jellyfin, go to Dashboard → Plugins, open Playback Reporting, and uninstall it
  2. Restart Jellyfin
  3. Reinstall Playback Reporting from the catalog and restart again
  4. Back in Tracearr, click Check Plugin again

Your history is safe. The plugin keeps its database at playback_reporting.db in Jellyfin’s data folder, outside the plugin folder that uninstalling removes.

Nothing on the Tracearr side can work around this; the exception is thrown inside the plugin before Tracearr’s query is read. See issue #1001  for the full trace and the upstream Jellyfin and plugin changes.

Disabling IPv6 in Docker

If you get “cannot reach [Plex/Emby/Jellyfin] server … fetch failed” when adding your media server

This is commonly caused by IPv6 resolution issues inside the Docker container. If your media server’s hostname resolves to an IPv6 address but the network path doesn’t fully support IPv6, the connection will fail.

To fix this, disable IPv6 inside the Tracearr container by adding sysctls to your Docker Compose file:

services:
  tracearr:
    image: ghcr.io/connorgallopo/tracearr:latest
    # ... your existing config ...
    sysctls:
      - net.ipv6.conf.all.disable_ipv6=1

After adding this, recreate the compose stack:

docker compose -f your-compose-file.yml down
docker compose -f your-compose-file.yml up -d

This forces the container to use IPv4 only, which resolves the issue in most cases.

Sessions aren’t being tracked

  1. Verify the server connection is active in Settings → Servers
  2. Check that your API key or token is still valid
  3. Start a playback session — Plex sessions appear instantly, while Jellyfin and Emby sessions appear within a poll cycle

Jellyfin or Emby sessions are slow to appear

Plex pushes sessions to Tracearr instantly over SSE. Jellyfin and Emby are polled on an interval by default, so their sessions can take a poll cycle to show up.

Install the Tracearr SSE plugin on your Jellyfin or Emby server for instant, push-based sessions. See the Real-Time Updates guide for setup.

I don’t see any location data / Everything shows as local

Note: Local streams (those originating from your home network) will never show location data — this is expected behavior. Geolocation only applies to remote streams from outside your network. If your remote streams are showing as “local” or missing location data, continue reading.

Tracearr uses client IP addresses reported by your media server to determine geolocation. If remote sessions show as “local” or have no location data, your media server isn’t seeing the real client IPs — usually because a reverse proxy is in front of it.

Two things need to be configured:

  1. Your reverse proxy must forward the real client IP via headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host)

  2. Your media server must be configured to trust those headers:

    • Jellyfin: Add your reverse proxy’s IP to Settings → Networking → Known Proxies
    • Emby: Add your reverse proxy’s IP to Settings → Networking → Known Proxies
    • Plex: Generally handles this automatically, but check Settings → Network → List of IP addresses and networks that are allowed without auth

See the Jellyfin reverse proxy documentation  for detailed configuration examples for Nginx, Caddy, Apache, Traefik, and more. The reverse proxy concepts apply to all media server types.

Quick checklist:

  • Reverse proxy sets X-Forwarded-For to the client’s real IP
  • Media server’s “Known Proxies” includes your reverse proxy’s IP address
  • For Docker setups, ensure the proxy sees real client IPs (not Docker network IPs)

If Tracearr itself is behind a reverse proxy, see the Reverse Proxy section of the environment variables reference for the TRUST_PROXY and CORS_ORIGIN settings.

The location data is wrong / IP geolocation is inaccurate

IP-based geolocation is inherently imprecise. Here’s why:

  • ISPs assign IPs regionally, not by exact address — your IP might be registered to a city 50+ miles away
  • Mobile carriers and VPNs often show locations far from the actual user
  • IP databases are updated periodically, so recently reassigned IPs may show old locations
  • Some ISPs route traffic through central hubs, making all users appear in one location
  • CGNAT (Carrier-Grade NAT) — Many ISPs, especially mobile carriers, use CGNAT where thousands of customers share the same public IP address. This means the IP geolocates to the carrier’s infrastructure (often a data center), not the user’s actual location. CGNAT is increasingly common as IPv4 addresses become scarce.

How Tracearr handles geolocation:

By default, Tracearr uses the MaxMind GeoLite2  database locally — all IP lookups happen on your server and no data is sent externally. This keeps your users’ IP addresses private.

Enhanced GeoIP option:

In Settings → General, you can enable “Enhanced GeoIP Lookup”. When enabled, Tracearr sends IP addresses to Plex’s GeoIP service (plex.tv/api/v2/geoip) which may return more accurate results. This works for all media servers, not just Plex. The local MaxMind database is used as a fallback.

OptionPrivacyAccuracy
Default (MaxMind)All data stays localGood for most cases
EnhancedIPs sent to plex.tvPotentially more accurate

Bottom line: IP geolocation will never be as accurate as GPS. It’s best used for detecting general regions and impossible travel scenarios, not pinpointing exact addresses.

How do I reset my Tracearr password?

You can reset your password using the built-in CLI script. No access to the web UI is required.

This resets the password for your Tracearr user account, not your media server accounts.

It works for any user, including accounts that only ever signed in with Plex: if the account has no local password yet, the reset creates one. As a security measure, resetting a password also signs out all of that user’s existing sessions.

# Interactive mode (you will be prompted to enter a new password)
docker exec -it tracearr node apps/server/dist/scripts/reset-password.js
 
# Non-interactive mode (sets password to "newpassword123")
 
docker exec -it tracearr node apps/server/dist/scripts/reset-password.js newpassword123

Tracearr also ships a fuller admin recovery CLI with commands for resetting passwords, changing usernames and emails, listing users, and re-enabling local login:

docker exec -it tracearr node apps/server/dist/scripts/cli.js <command>

See Account Recovery for all commands and lockout scenarios.

Server Resources is empty

What the Server Resources panel needs depends on the server:

  • Plex requires Plex Pass: resource monitoring is a Plex Pass API feature, and Tracearr currently does not detect whether your account has it.
  • Jellyfin and Emby don’t expose CPU or memory through their APIs at all. Installing the SSE plugin (v0.4 or newer) fills the panel with a live sample every 6 seconds. Host-level values require the media server to run on Linux, including in a container.

If the panel is empty, the server you’re looking at is missing its respective requirement above.

Pages are slow to load on Unraid

If Tracearr feels sluggish — especially pages with lots of history — the most likely cause is where your database is stored.

Paths under /mnt/user go through Unraid’s FUSE filesystem layer (shfs), which adds significant overhead to every database read and write. This affects all applications that use a database, not just Tracearr. On a typical Unraid setup, database operations through /mnt/user can be 50–100x slower than direct disk access, even on NVMe drives.

Fix: Move your PostgreSQL data to a path that bypasses the array:

  • /mnt/cache/appdata/tracearr/postgres — if you have a cache pool (most common)
  • /mnt/appdata/tracearr/postgres — if you’ve set up a dedicated appdata share on cache

If you’re using the supervised image from Community Apps, edit the container and change the PostgreSQL Data path. If you’re using Docker Compose with named volumes, this doesn’t apply — Docker manages the volume storage directly.

My newsletter says it sent but nobody got it

Open the newsletter and read the History tab. Every send lists its recipients with a per-address status of Queued, Sent, Failed, Suppressed or Unknown, so an address that was skipped says why on its own row.

Three things to check. An address on the suppression list under Settings → Notifications → Email is skipped on every newsletter, and shows as Suppressed. A newsletter covering several servers is split into one email per group of members, and a group whose servers added nothing in the window is mailed nobody; the editor’s Readiness list warns about that before you send. And members with no address anywhere are listed separately in the recipients panel rather than mailed.

Newsletter item links come from the server’s Public address, which is a separate field from the Server URL and is blank until you fill it in. Without it, or with an address a member off your network could not open, the links are left out and the newsletter editor’s Readiness list names the server. See Public address.

Data & Maintenance Jobs

Tracearr includes maintenance jobs in Settings → Jobs to fix common data issues.

I see inconsistent device names like “AndroidTV”, “Android TV”, and “NVIDIA Shield”

Run Normalize Players in Settings → Jobs. This standardizes device and platform names so they group correctly in charts and filters.

I see both “US” and “United States” in my country data

Run Normalize Countries in Settings → Jobs. This converts full country names to standard codes so your world map and country filters work properly.

My imported Tautulli sessions show 0% progress

Run Fix Imported Progress in Settings → Jobs. This recalculates progress values for imported sessions that have duration but missing progress data.

Users show “Never” for last activity even though they have watch history

Run Backfill User Dates in Settings → Jobs. This scans session history to populate the first seen and last activity timestamps.

My Library Growth charts are empty or missing historical data

Run Backfill Library Snapshots in Settings → Jobs. This generates historical data points from your library items.

My analytics numbers look wrong or charts show gaps

Run Full Aggregate Rebuild in Settings → Jobs. This recalculates all statistics from scratch.

A job says “already running” but I don’t see any progress

Go to /debug (e.g., http://your-tracearr:3000/debug) and click Clear Stuck Jobs. A previous job crashed and left stale state.

Last updated on
API Reference