Skip to main content

​
Streams show as Failed after generation

Failed streams couldn’t be matched to a real sporting event. Common causes:
  • Stream name too vague — Names like “Sports 1” or “NBA 3” don’t contain team names. Teamarr needs identifiable team or event information in the stream name.
  • League not subscribed — The stream’s league isn’t enabled in Event Groups > Global Defaults. Enable the league and regenerate.
  • Team name mismatch — Your IPTV provider uses a non-standard name. Add a team alias to map it to the official name.
  • Date format mismatch — Streams with dates in DD/MM format may be parsed as MM/DD. Use custom regex extractors with named groups ((?P<day>...)/(?P<month>...)) to fix the parsing order.
Click the Failed count in the run history to see details for each unmatched stream. Use the Fix button to manually match a stream to an event.

​
Streams matching the wrong event

  • Check the Detection Library for conflicting league or sport hints. A hint that’s too broad may be pulling streams into the wrong league or sport bucket.
  • Verify your stream filters (include/exclude regex in Event Groups) aren’t too broad.
  • Use the preview button on the Event Groups page to inspect matches without running a full generation.

​
Channels not appearing in Dispatcharr

  1. Verify Dispatcharr integration is connected — Settings > Dispatcharr should show Connected.
  2. Verify an EPG source is selected in Settings > Dispatcharr.
  3. Run EPG generation and confirm streams matched successfully.
  4. Check channel lifecycle timing — channels may not be created yet based on your Create Timing setting.

​
Channels disappearing unexpectedly

  • Check your delete timing — channels are deleted based on the post-event buffer.
  • Review the Recently Deleted section on the Channels page to see what was removed and when.
  • If using Same day delete timing, channels are removed at midnight on the day of the event.

​
Channel numbers colliding with existing channels

Set the Channel Range Start in Settings > Channels to a range that doesn’t overlap with your existing Dispatcharr channels. For example, if your existing channels occupy numbers 1–500, set the start to 1000.

​
Stale logos in media server

Some media servers — particularly Jellyfin — cache channel logos aggressively. Enable Scheduled Channel Reset in Settings > EPG to periodically purge and recreate channels before your media server’s guide refresh.

​
”Connection error” when testing

  • Verify the URL includes the protocol (http:// or https://).
  • Check that Dispatcharr is running and accessible at the configured port.
  • If running both in Docker, confirm the containers are on the same Docker network, or use the correct IP/hostname instead of localhost.
  • Check for firewalls or network rules blocking the port.

​
EPG source dropdown is empty

You need to add Teamarr’s XMLTV URL as an EPG source in Dispatcharr before it appears in the dropdown. Copy the XMLTV URL from the EPG page in Teamarr and add it in Dispatcharr’s EPG Sources settings.

​
Generation takes too long

  • Reduce Event Lookahead in Settings > Event Groups — a shorter window means fewer events to check.
  • Reduce Schedule Days Ahead in Settings > Teams — fewer days means less schedule data to fetch.
  • Use per-group subscription overrides to limit which leagues each event group scans.
  • Ensure the team/league cache is fresh — Settings > System > Refresh Cache.

​
Generation fails or shows errors

Check the logs for details:
# Docker container stdout
docker logs --tail 200 teamarr

# Log file inside the data volume
tail -n 200 data/logs/teamarr.log
Common causes:
  • Network timeout reaching ESPN or TSDB APIs
  • Dispatcharr API returning errors (check Dispatcharr’s logs as well)
  • Database locked — this shouldn’t happen in normal operation. Restart Teamarr if it does.

​
Startup crash after upgrade

If Teamarr fails to start after pulling a new image, check the logs for migration errors:
docker logs --tail 200 teamarr
Key rule: never delete teamarr.db. The database contains all your configuration — teams, templates, event groups, and settings. Schema changes are handled automatically through migrations. Deleting the database causes permanent data loss and is never required.If upgrading from a version older than 2.1.2, the migration path runs automatically. If it doesn’t succeed, file a bug report with the full error message from the logs.

​
Restoring a backup

Go to Settings > System > Backup & Restore and upload a .db backup file. Teamarr automatically creates a backup of your current database before overwriting it. Restart the application after the restore completes.
Teamarr writes to two log files in the data/logs/ directory:
FileContentsRotation
teamarr.logAll messages (DEBUG and above)10 MB × 5 files
teamarr_errors.logErrors only10 MB × 3 files
The console log level is controlled by the LOG_LEVEL environment variable (default: INFO). File logs always capture DEBUG regardless of this setting.Docker commands to view logs
# Container stdout (recent)
docker logs --tail 100 teamarr

# Main log file
docker exec teamarr cat data/logs/teamarr.log

# Errors only
docker exec teamarr cat data/logs/teamarr_errors.log
Environment variables
VariableDefaultDescription
LOG_LEVELINFOConsole log level: DEBUG, INFO, WARNING, ERROR
LOG_FORMATtextLog format: text or json
LOG_DIRAuto-detectedOverride the log directory path

​
Getting help

  • GitHub Issues — github.com/Pharaoh-Labs/teamarr/issues for bug reports and feature requests
  • Discord — Join the Dispatcharr Discord server. There is a dedicated Teamarr channel for community support.

Build docs developers (and LLMs) love

Get started for freeTalk to us