Troubleshooting

Two ways in. Scan the symptom index for a line that sounds like what you are seeing, or search the error index for the text on your screen. Every entry points at the page that explains it.

The rest of this section is procedure rather than pointers. Collecting Logs has the log commands for each install path. Reporting a Bug covers what belongs in a report.

Symptom Index

Connecting a Media Server

• Tracearr can’t connect to my media server
• Jellyfin stopped working right after I upgraded it to 12
• Adding a server fails with a fetch error inside Docker
• I deleted or regenerated my Jellyfin or Emby API key
• Adding a server again created a second copy of it
• My Plex servers stopped working after I changed my Plex password
• I can’t unlink a Plex account
• Check Plugin says Playback Reporting isn’t installed when it is
• Migrations fail against a PostgreSQL server I run myself

Sessions and Real-Time Updates

• Sessions aren’t being tracked
• Jellyfin or Emby sessions are slow to appear
• The real-time badge never shows up on my server card
• The stream connects and then nothing arrives
• Events stall behind my reverse proxy
• My client keeps getting disconnected
• I can’t tell whether to use webhooks, the WebSocket API, or SSE
• Server Resources is empty

Locations and Geolocation

• I don’t see any location data and everything shows as local
• The location data is wrong
• Country detection looks wrong on an automation

Signing In

• I forgot my Tracearr password
• I used to sign in with Jellyfin credentials and now I can’t
• Local login is disabled and my SSO is broken
• I don’t know which account is which any more
• Login works on the local address but not through my reverse proxy
• Everyone got signed out after an upgrade
• The setup page is asking me for a claim code

The Mobile App

• The QR code won’t pair
• The app can’t connect to my server
• I’m not getting push notifications
• The home screen widget isn’t updating
• A device shows “Last seen” a long time ago
• I can’t add another device
• My phone had to pair again after sitting idle

Automations

• An automation isn’t firing
• An automation is firing too often
• A share code someone sent me won’t import

Email and Newsletters

• The test email fails
• I don’t know what to put in the SMTP username and password
• A newsletter says it sent but nobody got it
• Members get no links to items on my Jellyfin or Emby server
• The unsubscribe link shows a login page

Importing History

• Records were skipped during a Tautulli import
• Records were skipped during a Jellystat import
• Records were skipped during a Playback Reporting import
• My imported sessions have no location or stream details
• My Tautulli history imported before Tracearr 1.3.9 shows no progress
• The plugin is already gone from my server

Jobs and Data

• A job says “already running” and nothing is progressing
• I see inconsistent device names
• I see both “US” and “United States” in my country data
• Users show “Never” for last activity
• My Library Growth charts are empty
• My analytics numbers look wrong or my charts show gaps
• I want to clear violations, rules, or sessions and start over

Backups and Restores

• The restore option is disabled on my backups
• Restoring a large database runs the container out of memory
• My backups aren’t on the host filesystem
• Tracearr can’t write to my backup directory

Installing and Upgrading

• My stack deploys from a Docker UI but Tracearr never starts
• My container names don’t match the ones in the documentation
• PostgreSQL refuses to start after I switched between standard and supervised
• The supervised container restarts in a loop and never turns healthy
• The supervised container gets killed with exit code 137
• Real-time updates die after 60 seconds on Kubernetes
• Job queues corrupt on the Redis I brought myself
• I don’t know how to update my Proxmox VE LXC

Performance

• Pages are slow to load on Unraid
• Database writes are slow on a path under /mnt/user

Remote Access

• Tracearr can’t reach other devices on my tailnet
• Tracearr won’t act as an exit node or a subnet router

Logs and Diagnostics

• I don’t know where my logs are
• The log command I was given returns nothing useful
• I need version, memory, and database numbers for a report
• My issue was closed for missing information

Error Message Index

Match the text on your screen against the strings below.

Media Server Connections

cannot reach [Plex/Emby/Jellyfin] server ... fetch failed

This comes up while adding a media server, usually from IPv6 resolution inside the container. See Disabling IPv6 in Docker.

That address or API key reaches a different server. A server can only be pointed at itself.
Could not read which server answers at that address.
Tracearr has no record of which server this is and cannot reach it with the saved address and key, so it cannot confirm the change points at the same server.
Jellyfin rejected this API key (it may be invalid or expired).
Emby rejected this API key (it may be invalid or expired).

The first three come from saving a new URL or API key in Edit Server. The last two can also come from Add Server. See Changing the URL or API key.

That Plex sign-in was for a different account. Sign in as <username> to reauthorize it.
Cannot unlink this Plex account. Please delete the <n> server(s) connected through this account first.
Cannot unlink your only login account. Set a password first or link another Plex account with login enabled.

All three come from Settings → Servers → Plex accounts. See Reauthorizing an account and Unlinking an account.

jellyfin request failed: 500 Internal Server Error

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

The first appears on the Import page after Check Plugin. The second is the matching entry in the Jellyfin log. Both point at Playback Reporting on Jellyfin 10.11.9+.

The SSE Plugin

401 Unauthorized

The token isn’t reaching the server in a form it accepts. See 401 Unauthorized.

404 Not Found

Either the path is wrong for your server type or the plugin isn’t loaded. See 404 Not Found.

disconnected on buffer overflow

Your client is reading slower than events arrive. See Client Keeps Getting Disconnected.

Email

SMTP authentication failed for <username> at <host>
Could not connect to <host>:<port>
TLS failed for <host>:<port>; check the security setting
host: host must be a hostname or IP address without a scheme, port or path
No alert recipients on this destination. Add one under Settings, Destinations.

All five come from an email destination. The first three come from the Test button or from an alert on its way out, the fourth from saving the destination, and the last when an automation sends to one whose alert recipient list is empty. See Errors from the mail server.

ENCRYPTION_KEY is set but is not 64 hex characters; fix or unset it

The server refuses to start on this. See Authentication Secrets.

Logs and the Debug Page

No such file or directory

The supervised log paths under /var/log/supervisor/ do not exist on a standard image. Pick your own install path in Collecting Logs.

PostgreSQL Database directory appears to contain a database; Skipping initialization

PostgreSQL init process complete; ready for start up

A captured database log that ends on one of these lines and holds nothing else is missing its stderr. PostgreSQL writes almost everything there. Collecting Logs has the redirect that keeps it.

Log explorer is only available in supervised mode

The Log Explorer switches on the image tag, so a pinned digest or a retagged image loses it even when the files are present. See the Debug Page.

Messages in the Web UI

That doesn't look like a Tracearr share code
This code looks cut off
That's too big to be a Tracearr automation
This needs Tracearr 2.2.0 or newer
That's a lot of codes in one minute

All five come from pasting a share code. See Codes That Won’t Read.

already running

A job in Settings → Jobs that says this without progressing has stale state from a previous crash. See the FAQ entry.

Invalid QR code
Pairing Failed

Pairing tokens last 15 minutes and work once. See Mobile App troubleshooting.