Skip to content

Troubleshooting

Jump to bottom
RetroIPTVGuide Wiki Sync edited this page Jun 15, 2026 · 2 revisions

Troubleshooting

This page covers common problems and how to fix them.

Installer Asks to Clone from GitHub Unexpectedly

Symptom: Running the installer prompts:

"The full RetroIPTVGuide repository was not detected in the current directory. The installer needs to clone it from GitHub…"

Cause: The installer checks for app.py and requirements.txt in the same directory as the script. If those files are absent it assumes the full release was not downloaded and offers to clone from GitHub.

Common causes and fixes:

Situation Fix
Ran curl … | sudo bash — full repo was never downloaded Answer yes to let the installer clone, or use --yes to skip the prompt
Extracted the release ZIP but ran the script from a different directory cd into the extracted directory first, then re-run the script
Only the installer script was downloaded, not the full archive Download the full .zip or .tar.gz from the Releases page and extract it, then run the script from inside that folder
Windows: running from a path other than the extracted folder Open PowerShell inside the extracted folder and run .\retroiptv_windows.ps1 install

Symptom: http://<server-ip>:5000 does not load.

Checks:

  1. Confirm the container or service is running: 
    docker compose ps
# or
sudo systemctl status retroiptvguide
  2. Confirm port 5000 is not blocked by a firewall: 
    sudo ufw status
  3. Confirm you are using the correct IP address of the server, not localhost when accessing from another device.
  4. If running Docker with a custom port mapping, use the mapped host port.

Guide Shows No Channels

Symptom: The guide loads but shows no channels or programs.

Checks:

  1. Confirm at least one tuner is configured under Tuner Management.
  2. Verify the playlist URL is reachable from the server: 
    curl -I "http://your-playlist-url/playlist.m3u"
  3. Verify the XMLTV EPG URL is reachable from the server: 
    curl -I "http://your-epg-url/epg.xml"
  4. Trigger a manual refresh from Tuner Management and check the application logs for errors.

Video Will Not Play

Symptom: Clicking a channel shows a black player or an error.

Checks:

  1. Confirm your IPTV backend provides HLS segmented streams (.m3u8 segment manifests), not MPEG-TS. RetroIPTVGuide relies on the browser's native HLS support or hls.js for playback and cannot play MPEG-TS streams directly.
  2. Open the browser developer console (F12) and check the Console and Network tabs for errors.
  3. Confirm the stream URL is reachable from the client device (not just the server).
  4. Test the stream URL directly in VLC or another player.
  5. Try a different browser. Chromium-based browsers (Chrome, Edge) generally have the best HLS compatibility.

Admin Password Lost

If the admin password is unknown it can be reset from the command line.

Linux / Raspberry Pi:

sudo -u iptv python3 /home/iptv/iptv-server/scripts/reset_admin_password.py \
  --db /home/iptv/iptv-server/config/users.db

Docker:

docker compose exec retroiptvguide \
  python3 /app/scripts/reset_admin_password.py --db /app/config/users.db

On success the password is reset and the account is flagged to require a new password on next login.

Permission Error on Reset

If the script reports a database write error, run it as the user that owns the database file:

ls -la /home/iptv/iptv-server/config/users.db
sudo -u iptv python3 /home/iptv/iptv-server/scripts/reset_admin_password.py \
  --db /home/iptv/iptv-server/config/users.db

Immutable File (Rare)

If the issue persists, check if the file has been made immutable:

lsattr /home/iptv/iptv-server/config/users.db

Remove the immutable flag if present:

sudo chattr -i /home/iptv/iptv-server/config/users.db

Virtual Channel Shows No Data

Symptom: A virtual channel loads but displays an error or empty content.

Checks:

  1. Confirm the channel is enabled under Virtual Channels.

  2. Confirm the channel has been configured (location for Weather, RSS URLs for News, region for Traffic, etc.).

  3. Check that the relevant external API is reachable from the server. Many virtual channels rely on public internet APIs:

    Channel External API
    Weather (conditions/forecast) api.open-meteo.com
    Weather (alerts, US only) api.weather.gov
    Weather (radar) opengeo.ncep.noaa.gov
    News Configured RSS feed URLs
    Traffic overpass-api.de
    Sports User-configured external data source (RSS feeds or JSON scores endpoint)
    NASA api.nasa.gov
    On This Day en.wikipedia.org

  4. Run Admin Diagnostics to check connectivity to each virtual channel data source.

Data Not Persisting After Docker Update

Symptom: Tuners, settings, or users are lost after updating the container.

Cause: The data directory is not mounted as a persistent volume.

Fix: Mount /app/config as a Docker volume in docker-compose.yml:

volumes:
  - ./config:/app/config

After adding the volume, recreate the container:

docker compose down && docker compose up -d

Database Errors on Startup

Symptom: Application logs show SQLite errors or schema migration warnings.

Checks:

  1. Confirm the data directory is writable by the application user.
  2. Check for disk space issues: 
    df -h
  3. If the database files are corrupt, stop the application, back up the files, and remove them. The application will recreate them on next start (you will need to reconfigure tuners and users).

EPG Times Are Incorrect

Symptom: Program times in the guide are offset from the correct time.

Checks:

  1. Confirm the TZ environment variable (Docker) or system timezone matches your local timezone.
  2. Confirm the XMLTV EPG source includes correct timezone offsets in its timestamps.

Running Admin Diagnostics

The built-in Admin Diagnostics page provides a comprehensive health check:

  1. Log in as an administrator.
  2. Navigate to Admin → Diagnostics.
  3. Review the status of each check, including virtual channel connectivity, database schema, and system health.

Diagnostics check virtual channel external service connectivity, database schema integrity, user account configuration, and more.

Still Stuck?

Check the application logs for additional error details:

# Docker
docker compose logs -f

# Linux (systemd)
journalctl -u retroiptvguide -f

Open an issue on GitHub with the RetroIPTVGuide version, installation type, relevant log output, and reproduction steps: https://github.com/thehack904/RetroIPTVGuide/issues

Clone this wiki locally