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
• 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
• 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

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 imported Tautulli sessions show 0% 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.

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.

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.