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.

Can the people I share my server with sign in?

Yes, since 2.8.0, with the Plex, Jellyfin or Emby account they already have on your server. It is off until you turn on Let admins and members sign in under Settings → Access → Sign-in and switch on the servers they may use, or set a person to Allow on their user page. A member sees their own plays; other people’s activity shows only as anonymous counts, and only if you turn on Show members anonymous server activity. See Member sign-in.

Can I change the owner or add another Tracearr account?

No. The owner is the account created at first-run setup. Tracearr never creates a second Tracearr account, and nobody can be given the owner role later. Everyone else is a person synced from your media servers, who can sign in with their own Plex, Jellyfin or Emby account once you allow it. If the owner was set up apart from your own media server account, The owner account explains what that means.

The web app cannot change a username. The set-username recovery command can, but a new username does not link the owner to any media server account.

How do I merge two users into one person?

On Users, select the two people and click Merge users. Only the owner has the button. The dialog shows which person is kept and which is folded in and then deleted, and Swap which one is kept changes that. The owner, an admin, or anyone with a Tracearr password or SSO login is always the one kept, and two such people cannot be merged into each other. Signing in with Plex, Jellyfin or Emby does not count toward this.

The folded-in person’s server accounts and sessions move to the kept person, and you can split an account back out from the kept person’s page later. If both people have an account on the same server, those two accounts become one, and splitting does not separate them again.

Tracearr also suggests merges on that page for people whose server accounts share an email address or a username.

The owner is not listed on Users, so your own Jellyfin or Emby account is not merged there. Link it from its server instead; see Linking your own Jellyfin or Emby 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. A replaced Jellyfin or Emby key goes in Edit Server, see Changing the URL or API key
  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. A replaced Jellyfin or Emby key goes in Edit Server, see Changing the URL or API key
  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 from your home network) have a private IP that no geolocation database can place, so they show as Local Network and stay off the map. To put them on the map, give the server a location. 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 resets the owner’s password, and works even when the owner only ever signed in with Plex: if there is no local password yet, the reset creates one. To reset an admin’s password, run cli.js reset-password <username> instead; members sign in with their media server account, not a password. 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 on 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 overhead to every database read and write, even on NVMe drives. This affects every application that keeps a database there, not only Tracearr. A path that names the pool directly, such as /mnt/cache/..., skips that layer.

The supervised image from Community Apps checks this each time it starts. When the database, Redis or app data sits on a user share, the owner sees a banner, and Show me how to fix it lists the template field to change and the exact path to set, built from your own pool’s name.

Fix: In Unraid, open Docker, click the Tracearr icon and choose Edit. Change PostgreSQL Data to the same folder on its pool, /mnt/<pool>/appdata/tracearr/postgres, where <pool> is your pool’s name (cache on most setups). Click Apply.

Only switch once every file in that folder is on the pool. The supervised image creates a new, empty database when the PostgreSQL Data folder has no PG_VERSION file, so pointing it at a pool folder that’s missing files starts Tracearr from scratch. If part of appdata is still on the array:

  1. Stop the Tracearr container.
  2. In Shares, open appdata. Set Primary storage to your pool, Secondary storage to Array, and Mover action to Array → pool.
  3. In Main, click Move and wait for it to finish.
  4. Start Tracearr. Once every file is on the pool, the in-app notice shows the exact path to set.

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.

I set a server location but past local plays still show as Local Network

Saving a server location runs Apply Server Locations on its own. If another job was running at the time, it starts when that one finishes. If past plays still show as Local Network after that, run Apply Server Locations in Settings → Jobs, which rechecks every server.

My Tautulli history imported before Tracearr 1.3.9 shows no progress

Run Fix Imported Session Progress in Settings → Jobs. It estimates progress and length for plays that have neither, and never changes a play that already has either value.

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.

Storage Trend still shows media I deleted

The Storage Trend and Quality Evolution charts read stored daily snapshots of each library, not the library as it is now. A snapshot records one library’s item count and total size for one day, and once a day is recorded Tracearr does not go back and change it. Deleted media shows up as a drop on the day a library sync noticed it was gone. Every day before that still counts it, because it was on the server then.

Snapshots are written two ways. Each library sync records today’s. When a sync finds no history, a gap, or an item older than the earliest day on record, Tracearr queues Backfill Library Snapshots, which reconstructs the missing days from each item’s added date as the media server reports it. So a server that reports the wrong added date produces wrong history. An item it says was added in 2015 is counted in every day from 2015 on, and the chart starts in 2015, even after the item is deleted.

Running the backfill again does not correct this. It only writes days that have no snapshot yet, and days already on record keep their values.

Deleted media can’t be rebuilt. The backfill only reads items that are still in the library, with the files they have now. A deleted title, or the file an upgrade replaced, leaves it nothing to look back at, so that item’s share of past days exists only in the snapshots already stored. Delete those snapshots and the history goes with them. A rebuild draws the curve as if the library had always held exactly what it holds today.

If you want the bad stretch gone anyway:

  • Snapshot Management on the debug page loads the 100 most recent snapshots. It handles a bad day or two from recent syncs, but it can’t reach years-old rows.
  • Clear Library Cache in the debug page’s Danger Zone deletes every library item and every snapshot. The next library sync reads your libraries again and queues the backfill, which rebuilds the history from the added dates your server reports now. This is the only way to remove a long stretch of bad history, and it loses the record of everything deleted or upgraded before it. It also resets when Tracearr first saw each title, so the next newsletter lists your whole library as new.

Fix the added dates on the media server first. A rebuild from dates that are still wrong reproduces the same history.

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