EPG Collector: Complete Guide to Gathering TV Program Data

Troubleshooting Your EPG Collector: Common Issues & Fixes

An Electronic Program Guide (EPG) collector aggregates broadcast schedule data from XMLTV, DVB streams, web scrapers, and APIs. When it fails, your channel listings, recordings, and user experience suffer. Below are the most common issues, diagnostic checks, and step-by-step fixes to get your EPG collector back to reliable operation.

1. No data or empty guide

Symptoms: EPG shows no channels or program entries; guide import reports zero items.

Quick checks:

• Confirm the collector service/daemon is running.
• Verify network connectivity to data sources.
• Check disk space where the EPG database and cache are stored.

Fixes:

1. Restart the collector service:
   • Linux: systemctl restart epg-collector (or your service name)
   • Docker: docker restart
2. Inspect logs for errors (paths vary; common: /var/log/epg-collector.log).
3. If using remote XMLTV/URL sources, open the URL in a browser or use curl:

   Code
   Copy CodeCopied
   curl -I “https://example.com/epg.xml”
   

   If it fails, contact the source or update credentials.

4. Rebuild the EPG database/cache:
   • Stop service, delete the database/cache file(s), start service to force re-import.
5. Ensure scheduled fetch/crons are enabled and the system clock is correct.

2. Missing channels or mismatched channel IDs

Symptoms: Some channels absent; listings present but assigned to wrong channels.

Quick checks:

• Compare channel list from source (XMLTV channels tag, DVB service list) with your collector’s channel map.
• Look for channel ID changes from upstream providers.

Fixes:

1. Update or refresh channel mapping file:
   • Map source channel IDs to your internal channel identifiers.
2. Use automated mapping tools (if available) to match by display-name and frequency/service ID.
3. Add fallback name-based matching when IDs change.
4. For DVB sources, re-scan frequencies and update service IDs in the collector config.

3. Duplicate program entries

Symptoms: Same program appears multiple times or overlapping entries exist.

Quick checks:

• Verify whether duplicates originate from multiple sources.
• Check time zone and UTC offsets in incoming data.

Fixes:

1. Deduplicate on import by unique keys (e.g., start time + channel ID + program title).
2. Normalize timezones: ensure incoming timestamps are parsed consistently (UTC vs local).
3. Configure a priority order for multiple EPG sources and discard lower-priority overlapping entries.
4. If duplicates persist from a single source, report upstream or add a source-specific filter.

4. Incorrect times or shifted schedules

Symptoms: Programs show at wrong times or appear shifted by an hour.

Quick checks:

• Confirm the collector’s timezone and system clock.
• Check timestamps in source XML (look for timezone attributes or UTC).
• Daylight saving time (DST) transitions recently occurred.

Fixes:

1. Set the server timezone correctly, or configure the collector to interpret all times as UTC.
2. Apply timezone offset handling in the import parser.
3. Update the collector to a version that handles DST correctly; apply patches if available.
4. When DST causes recurrent issues, add a DST-aware conversion routine during import.

5. Parsing errors or malformed source data

Symptoms: Import fails with parse errors; log shows XML/JSON parsing exceptions.

Quick checks:

• Inspect source file around the reported line/column.
• Confirm content type and encoding (UTF-8 vs others).

Fixes:

1. Implement robust parsing with try/catch and fallback handling for minor malformations.
2. If encoding issues exist, re-encode source (e.g., iconv -f WINDOWS-1252 -t UTF-8).
3. Request a corrected feed from the provider if the source is consistently malformed.
4. Add pre-parse cleanup scripts to strip invalid control characters or fix known provider quirks.

6. Authentication or access denied errors

Symptoms: ⁄₄₀₃ responses when fetching remote EPG feeds.

Quick checks:

• Verify API keys, tokens, or credentials haven’t expired.
• Confirm IP allowlists or rate limits with the provider.

Fixes:

1. Rotate or renew credentials and update the collector’s config.
2. Implement token refresh logic if the provider uses OAuth.
3. Whitelist your server IP with the provider or request higher rate limits.
4. Add retry/backoff logic for transient auth failures.

7. Slow imports or timeouts

Symptoms: Long fetch times, import jobs time out, or high CPU/IO during parsing.

Quick checks:

• Monitor network latency and bandwidth to sources.
• Check CPU, memory, and disk I/O during import.

Fixes:

1. Increase HTTP timeout and chunked download handling for large feeds.
2. Offload parsing to worker processes and use streaming parsers rather than loading entire files into memory.
3. Cache unchanged feeds and only process diffs when possible.
4. Optimize database writes with bulk inserts and proper indexing.

8. Database corruption or performance issues

Symptoms: Crashes, slow queries, or corrupted EPG DB files.

Quick checks:

• Run DB integrity checks (e.g., SQLite PR