Setup & Troubleshooting

IPTV EPG explained: how the electronic program guide works, and how to fix it

By Henry Hopkins · Reviewed by IPTV Americans Editorial Team · Published September 9, 2026 · Updated September 10, 2026 · 27 min read

What is an IPTV EPG?

An IPTV EPG — short for electronic program guide — is the on-screen schedule that shows what is playing on each channel right now, what is on next, and what is scheduled for the days ahead. It is the grid you scroll through in TiviMate, IPTV Smarters Pro, or a set-top box, and it is what makes catch-up, recording, and reminders possible at all.

The single most useful thing to understand about an IPTV electronic program guide is this: the guide is a completely separate feed from the video. Your channels arrive as one thing — a playlist of stream URLs. The schedule arrives as another — a data file full of programme titles, start times, and descriptions. The two are stitched together inside your player, on your device, after both have been downloaded.

That separation explains the situation almost everyone hits eventually: every channel plays perfectly, and the guide is completely empty. Nothing is down. One of the two feeds simply did not arrive, or arrived and could not be matched to the other. Our IPTV glossary entry for EPG covers the short definition; this IPTV EPG guide covers the mechanism.

The channel list and the guide are two different files

• The playlist (an M3U file, or an Xtream Codes login) tells the player which channels exist and where to fetch each stream.
• The EPG (usually an XMLTV file) tells the player what is scheduled on each of those channels, and when.

Two files, two URLs, two download jobs, two things that can fail independently. Keep that model in your head and most EPG IPTV problems become obvious rather than mysterious.

Where the guide sits in the rest of the stack

It helps to picture the whole chain at once, because the pieces fail in different places for different reasons:

1. Origin and edge servers carry the actual video. When these have a bad night you get buffering or a dead channel — never a blank guide.
2. The playlist is a list of channels and stream URLs, refreshed when you log in or when the player re-syncs.
3. The guide file is a schedule, regenerated on the provider's own timetable and served from what is often a different hostname or port than the video.
4. Your player downloads both, matches them, caches the result, and draws the grid.

That third point matters more than it sounds. Because the guide frequently lives on a different host or port from the streams, a network that blocks or mangles one will happily pass the other. It is the reason a VPN, a DNS filter, or a restrictive router can leave you with flawless video and an empty schedule — a combination that looks like a broken subscription and is nothing of the kind.

How an IPTV EPG works, stage by stage

Stage 1 — Schedule data is gathered at the source

Broadcasters publish their own schedules. Guide data for a large international lineup is assembled from those published schedules, per country and per network, and normalised into one consistent format. This is where the quality of a guide is actually determined: a channel whose schedule is not being collected at this stage cannot have a guide anywhere downstream, no matter what you change in your player.

It is also where the differences between services come from. Two providers can carry the identical channel and ship visibly different guides for it — one with episode titles, descriptions, and poster art, the other with a bare programme name — because they are drawing on different upstream schedule sources.

Stage 2 — The schedules are compiled into an XMLTV file

XMLTV is the de-facto standard format for TV listings. It is plain XML with two kinds of element: one declaring each channel, and one for each programme on it.

<channel id="espn.us">
  <display-name>ESPN</display-name>
</channel>

<programme start="20260910200000 -0400"
           stop="20260910230000 -0400"
           channel="espn.us">
  <title lang="en">NFL Regular Season</title>
  <desc lang="en">Live coverage.</desc>
</programme>

Two details from that snippet matter later. First, the timestamps are absolute and carry a UTC offset (-0400 here) — the guide always knows what time a programme starts, so time problems are display problems. Second, the channel attribute on the programme has to match the id on the channel element. That identifier is the hinge the whole system turns on.

Stage 3 — Your player downloads the guide

The player fetches the guide from an EPG URL. On an Xtream Codes setup it is usually derived automatically from the login you already entered, and looks something like this:

http://your-provider-host:port/xmltv.php?username=USERNAME&password=PASSWORD

On a plain M3U setup you paste the XMLTV URL manually, often as a compressed .xml.gz file. Either way this is a normal HTTP download of a file that can be several megabytes for a large lineup, which is why a guide refresh is not instant and why judging it three seconds after pressing refresh is the most common self-inflicted "IPTV EPG not working" report we see.

Stage 4 — The player matches guide rows to your channels

Your M3U playlist carries a tvg-id attribute on each channel:

#EXTINF:-1 tvg-id="espn.us" tvg-name="ESPN" group-title="US Sports",ESPN
http://your-provider-host/live/USERNAME/PASSWORD/12345.m3u8

The player looks for an XMLTV channel whose id equals that tvg-id. espn.us matches espn.us, so ESPN gets its schedule. If the playlist says espn.us and the guide says ESPN.us or espn.usa, there is no match and that one channel shows "No Information" while every channel around it looks fine. This is the entire explanation for the IPTV EPG missing on some channels but not others pattern.

Stage 5 — The guide is cached and refreshed on a timer

Downloading a multi-megabyte guide on every channel change would be unusable, so players store a local copy and refresh it on their own schedule — typically once or twice a day, plus whenever you force it. The cache is a performance feature that occasionally becomes a bug: if a partial or corrupt download is written to it, the player keeps serving that broken copy and reports success. That is why "clear the EPG cache" is a real fix and not superstition.

Inside an XMLTV file: the fields that actually matter

You will rarely need to open a guide file by hand, but knowing what is in one explains most of the differences between a guide that feels complete and a guide that feels thin. Here is a fuller example than the stripped-down snippet above.

The header tells you how fresh the guide is

<tv date="20260910040000 +0000"
    source-info-name="Provider Guide"
    generator-info-name="xmltv-generator">

The date attribute on the root element records when the file was generated at source. This is a genuinely useful number, and it is different from the "last updated" timestamp your player shows, which records when your device last downloaded a copy. If your player says it refreshed an hour ago but the file itself was generated two days ago, the staleness is upstream and no amount of refreshing will help.

The channel block

<channel id="espn.us">
  <display-name>ESPN</display-name>
  <display-name lang="en">ESPN USA</display-name>
  <icon src="https://example.com/logos/espn.png" />
</channel>

A channel can carry more than one display-name. That is not decoration — several players fall back to matching your playlist's tvg-name against these display names when the tvg-id does not match anything, so a guide with generous alternate names produces fewer blank channels. The icon element is where channel logos come from when your playlist has no tvg-logo of its own.

The programme block, in full

<programme start="20260910200000 -0400"
           stop="20260910230000 -0400"
           channel="espn.us">
  <title lang="en">Monday Night Football</title>
  <sub-title lang="en">Week 1 &#8212; opening night</sub-title>
  <desc lang="en">Live coverage of the opening fixture.</desc>
  <category lang="en">Sports</category>
  <episode-num system="xmltv_ns">0.2.0/1</episode-num>
  <icon src="https://example.com/art/mnf.jpg" />
  <new />
</programme>

Every one of those optional children drives something you can see on screen. category feeds genre filters and the colour coding some players apply to the grid. icon is where programme poster art comes from. new and its siblings produce the "New" badges. sub-title is the episode-title line under the programme name. When someone says a guide "works but looks empty", what they almost always mean is that it carries titles and times and none of these extras.

Episode numbering, and why series link depends on it

The episode-num element is worth understanding because it is unintuitive. The xmltv_ns system encodes season.episode.part and every number is zero-based, so 0.2.0/1 means season 1, episode 3, part 1 of 1. A second system, onscreen, carries the human-readable form instead:

<episode-num system="onscreen">S01E03</episode-num>

If a guide omits episode numbers entirely, your player has nothing to match on except the programme title. Series recording still appears to work, but it degrades into title matching, which is why it starts catching repeats and specials you did not want. A guide that carries proper episode numbering is doing real work for you even though you never see the field.

How your player actually fetches the guide

There are a few distinct delivery mechanisms, and knowing which one you are on narrows troubleshooting considerably.

A direct XMLTV URL

The simplest case: you paste a URL, the player downloads the file on a schedule. Everything is visible and testable, which makes this the easiest setup to diagnose — you can fetch the same URL yourself and see exactly what the player sees.

The Xtream Codes API

When you log in with a username, password, and host rather than pasting an M3U, the player talks to an API and derives both the playlist and the guide from it. The full guide lives at the xmltv.php endpoint shown earlier. There is also a per-channel endpoint that players use to fill in now/next quickly without re-parsing the whole file:

http://your-provider-host:port/player_api.php?username=USER&password=PASS&action=get_short_epg&stream_id=12345

One detail catches people out if they ever inspect this by hand: the response is JSON, and the programme titles and descriptions inside it are Base64-encoded. Seeing a wall of gibberish where the titles should be does not mean the data is corrupt — it means it has not been decoded yet.

Portal boxes and Enigma2 receivers

MAG boxes and other Stalker-portal devices work differently again: the portal serves the guide as part of the session, so there is no separate EPG URL for you to re-enter. Troubleshooting on those boxes is about the portal connection as a whole rather than the guide specifically. Enigma2 receivers typically pull listings through an import plugin on their own schedule, which means the guide can be stale for reasons that have nothing to do with your IPTV provider at all.

Compression, and why the file extension matters

Guide files are commonly served gzip-compressed as .xml.gz, because the saving on a multi-megabyte XML file is large. Some players decide whether to decompress based on the URL suffix rather than on what the server actually says in its response headers. The result is a specific and confusing failure: a URL ending in .gz that serves plain XML, or a URL ending in .xml that serves compressed data, parses to nothing and shows up as an empty guide with no error message. If you have both forms available from your provider, trying the other one is a thirty-second test worth running.

Why the IPTV program guide matters more than it looks

It is easy to write the guide off as decoration. It is not, because several other features are built on top of its data rather than beside it:

• Catch-up and replay. A catch-up player needs to know exactly when a programme started and ended to give you a replay window.
• Recording and series link. Recording "the 8pm game" means recording a programme entry, not a time range.
• Reminders and now/next. Both read directly from the guide.
• Channel surfing that is actually usable. With 59,000+ channels, browsing by what is on beats scrolling a list of names.
• A quality signal. Guide accuracy is one of the more honest indicators of how well a service is maintained, because it is unglamorous, ongoing work that nobody advertises.

Catch-up: how the guide becomes a replay window

This one deserves spelling out, because it generates a lot of misdirected support tickets. Catch-up is not a separate video library sitting alongside your channels. When you scroll back in the guide and select yesterday evening's programme, the player reads that programme's start time and duration from the EPG and uses them to construct a request against the provider's archive for that channel. The playlist declares that the capability exists:

#EXTINF:-1 tvg-id="espn.us" catchup="default" catchup-days="7" ...

But the EPG supplies the boundaries. The consequence is direct and catches people out constantly: a channel with no guide data has no catch-up, even on an account where catch-up is enabled and working everywhere else. There is nothing to scroll back through, because there are no programme entries to select. Most "catch-up isn't working" reports are EPG reports wearing a different hat.

Recording and series link

Recording works the same way. You are not recording a time slot, you are recording a programme object taken from the guide, which is why a recording follows a late-running programme in players that support it. Series link goes one step further and matches future programmes by title and, where the guide provides it, by episode number. This is exactly why the episode-num field discussed above is worth having: without it, series link falls back to title matching and starts recording every repeat.

One legitimate exception worth knowing

Pay-per-view and event channels frequently carry no listings until shortly before the event, because there is nothing scheduled to list. That is normal behaviour for live event channels, not a broken guide, and no amount of refreshing will populate them ahead of time.

How to set up an IPTV EPG in the main players

TiviMate

If you added your playlist through Xtream Codes, TiviMate normally picks up the EPG source on its own. If it did not, open Settings → EPG, add the XMLTV URL from your provider's activation email as an EPG source, then run Update now and wait for it to complete.

TiviMate is worth learning properly because it exposes the settings that cause most of the confusion later: how many days of guide to load and keep, how often to refresh automatically, and an EPG time shift. It also supports attaching more than one EPG source to a playlist, which is useful when your provider's guide is strong on domestic channels and thin on a handful of international ones — though see the warning about mapping further down before you start rearranging sources.

IPTV Smarters Pro

Logging in with Xtream Codes credentials pulls the guide automatically. If the grid is empty, use the refresh action in the EPG menu rather than reinstalling, and let it finish. Our IPTV Smarters Pro guide walks through the full setup including playlist entry.

Kodi with PVR IPTV Simple Client

Kodi keeps the playlist and the guide in the same place: the addon's own configuration, where you supply an M3U location and an XMLTV location as two separate settings. It also has its own EPG time-shift setting, distinct from Kodi's system clock, which is a common source of double-applied offsets. Changes to the addon's settings usually need the addon restarted — or Kodi restarted — before they take effect, which leads people to conclude a correct URL did not work.

Set-top boxes and Smart TV apps

On MAG-style portal boxes there is no EPG URL to manage, as described above. Built-in Smart TV apps vary enormously: some expose a full set of EPG controls, others expose nothing at all and simply show whatever the portal or API hands them. If a TV app gives you no guide settings and the guide is wrong, running an external player on a stick alongside it is usually faster than fighting the app.

Fire TV, Apple TV and Android TV

The device does not change how the EPG works — the player does. The same XMLTV file feeds every one of them. What does change is available storage and processing power, which matters more than people expect and is covered in its own section below. Setup by device is covered in the Firestick setup guide.

Set the clock before you judge the guide

Before deciding a guide is wrong, confirm the device's date, time, and time zone are correct, and that any manual EPG offset in the player is set to zero unless you deliberately need one. A player pointed at the right guide with the wrong clock produces a guide that looks broken but is fine.

Test the guide URL yourself: a five-minute diagnostic

This is the single most useful thing in this article, because it splits the problem cleanly in two. Either the guide file is fine at source and your player is the problem, or the file never arrives and your player is blameless. Ten minutes of guessing is replaced by one request.

A word of caution first. Your EPG URL usually contains your username and password in plain text. Do not paste it into public "check my URL" websites, do not post it in a forum thread asking for help, and crop it out of screenshots. Anyone holding that URL holds your account.

Step 1 — Fetch the headers

curl -sIL "http://your-provider-host:port/xmltv.php?username=USER&password=PASS"

You are reading three things: the HTTP status code, the content type, and the content length.

Step 2 — Interpret what came back

Step 3 — Check how fresh the file is

curl -s "YOUR-EPG-URL" | head -c 400

Read the date attribute on the opening <tv> element. That is the generation time at source. Compare it against the "last updated" figure in your player: if the player is current and the file is old, the staleness is upstream and there is nothing to fix on your device.

If the file is gzipped, pipe it through gunzip first:

curl -s "YOUR-EPG-URL" | gunzip | head -c 400

If that command errors out on a URL ending in .gz, you have found the compression mismatch described earlier — the server is sending plain XML under a compressed-sounding name.

Step 4 — Check a specific channel

If the guide downloads fine but one channel is blank, search the file for that channel's ID:

curl -s "YOUR-EPG-URL" | grep -o 'channel id="[^"]*"' | grep -i espn

If the ID is not there, no player setting will conjure it up and the fix is a provider-side one. If it is there but your channel is still blank, you have an ID mismatch and mapping will solve it.

IPTV EPG not working? Start by reading the symptom

The symptom tells you where the failure is. Working through this table first is faster than trying fixes at random.

The troubleshooting order that actually saves time

Work down this list rather than across it. Each step is cheap, and each one rules out a whole class of cause before the next.

1. Confirm it is an EPG problem (30 seconds)

Play two or three channels from different groups. If they play, your account, credentials, and connection are fine and this is a guide-data problem. If they do not, stop here — you are troubleshooting the wrong thing.

2. Force an update and watch the timestamp

Trigger a manual refresh and let it run to completion, then check that the "last updated" time actually changed. If it did and the guide is still empty, the download is succeeding but the matching is failing (jump to step 6). If it did not change, the download itself is failing (steps 3 and 4).

3. Re-add the EPG source URL

Remove the existing EPG source and re-enter it from your provider's activation email or the Xtream Codes API. An EPG URL that changed or expired is the usual cause of a guide that was working last week and is blank today.

4. Clear the EPG cache

If the player has been serving a corrupt or partial copy, clearing stored guide data and refreshing forces it to rebuild from scratch. Expect the first refresh afterwards to take longer than usual.

5. Fix the clock, then re-check

For a fixed-hour shift, correct the device time zone and enable automatic time, set the player's EPG offset back to zero, and refresh. Do not compensate for a wrong clock with a manual offset — the section below explains why that breaks twice a year.

6. Widen the EPG window

If only now and next appear, raise the number of days of guide the player loads and retains. Some players default to a short window to save storage, which looks identical to missing data.

7. Map the channels that are still blank

Whatever is still missing after steps 1–6 is almost certainly an ID mismatch. Use the player's EPG-to-channel mapping tool to link those channels manually, and send the list to support so the IDs can be fixed at source for everyone.

8. Rule out the network

A VPN, a DNS filter, or a restrictive network can block the guide download while leaving the video streams working, because they are different hosts and often different ports. Try once with the VPN off and on a different connection — a mobile hotspot is a fast test.

Each of these is expanded, with the exact menu paths per player, in our dedicated IPTV EPG not loading walkthrough.

Channel ID matching, in depth

Because mismatched identifiers cause the majority of partial-guide problems, it is worth understanding what your player is actually doing when it tries to attach a schedule to a channel.

What the player tries, and in what order

1. Exact ID match. The playlist's tvg-id against the guide's channel id. This is the only method that is reliable, and the only one a well-built playlist should need.
2. Display-name fallback. Several players then try the playlist's tvg-name or the visible channel name against the guide's display-name entries. This rescues some channels and mis-assigns others, which is how a channel occasionally ends up showing a schedule that belongs to a different network entirely.
3. Your manual mapping. Whatever you have linked by hand, stored locally by the player.

Why IDs drift in the first place

Identifiers are not supposed to change, but they do. A provider rebuilds a lineup and renames entries. A channel moves from one upstream guide source to another and arrives with a different ID convention. A regional variant is split into two entries where there was one. None of this is visible to you; it just shows up as a channel that had a guide last month and does not now.

The mapping warning nobody mentions

Manual EPG mapping is stored locally, per playlist, in most players. That has an important consequence: deleting and re-adding your playlist wipes every mapping you have made. This is the trap in the standard "just remove it and add it again" advice — it does fix some problems, and it silently destroys an afternoon of careful mapping in the process.

If you have mapped more than a handful of channels by hand, two habits are worth adopting. Keep a short note of which channels you mapped and to what, somewhere outside the player. And before any teardown-and-rebuild step, check whether your player offers a settings backup or export, because restoring one is faster than redoing the work. Reinstalling the player should stay what it is meant to be — the last resort, not the first move.

Time, time zones, and the twice-a-year breakage

A guide that is correct but displayed against the wrong clock is indistinguishable, at a glance, from a guide full of wrong data. These are the three ways it happens.

Why a manual offset is a trap

Every player offers an EPG time shift, and it is tempting to reach for it the moment the grid looks three hours out. Resist it unless you know why you need it. A manual offset is a fixed constant; daylight saving is not. Set an offset to paper over a wrong device clock in winter, and your guide will be an hour out from the spring change until you remember why. Guides that mysteriously break twice a year, on the same two weekends, are almost always carrying a manual offset that somebody set years ago and forgot.

Fix the device clock instead. The offset control exists for the genuine edge case where a source publishes times that are deliberately shifted, not as a general correction tool.

The missing-offset case

XMLTV allows the timezone portion of a timestamp to be omitted. When it is missing, the player has to guess what the time refers to, and different players guess differently. The tell is specific: if your guide is out by exactly your own UTC offset — five hours on US Eastern, eight on Pacific — rather than an arbitrary amount, a missing offset in the source file is the likely cause. That one is genuinely a source-side bug worth reporting, because the file is ambiguous rather than wrong.

The device clock itself

Enable automatic time and confirm the region, not just the hour. Two failure modes are common enough to check for directly: a box that loses its clock after a power cut and comes back set to the manufacturing date, and a device set to the right hour but the wrong region, which looks fine until a daylight-saving boundary that the two zones do not share.

When the guide is right but the programme is wrong

A different complaint from a blank guide, and a different set of causes. The listings are populated, plausible, and do not match what is on screen.

• Regional feeds sharing one guide entry. Many networks run several regional variants. If the guide carries one schedule for the network and you are watching a regional feed, local programming windows will not line up. Sports is where this bites hardest.
• "+1" and timeshift channels. A +1 channel broadcasts the base channel's schedule an hour later. If it has been mapped to the base channel's guide ID, every listing will be exactly one hour early — a fixed offset on one channel while the rest of the grid is correct.
• Late sports rescheduling. Fixtures move after the guide was generated. Nothing downstream can know about a change made after the file was built; it corrects itself at the next regeneration.
• Generic placeholders. Some sports channels are listed as "Live Football" or similar for a whole block rather than by fixture, because the upstream source publishes it that way. Thin, but not broken.

The distinction that matters when reporting one of these: a fixed offset on a single channel is usually a mapping problem somebody can fix, while a varying mismatch is usually a regional-feed mismatch that needs the right guide source attached.

How often should an IPTV EPG update?

There are two clocks running, and confusing them causes a lot of unnecessary worry.

The source clock: the XMLTV file itself is regenerated on the provider's schedule, commonly once or twice a day. Between regenerations, no amount of refreshing on your device produces newer data — you will re-download the same file.

The player clock: your app refreshes its local copy on its own interval, which you can usually configure, and always on demand.

So if the guide is a few hours behind a very late schedule change, that is the source clock and it will resolve itself. If the guide is a day or more stale and a manual refresh does not move the timestamp, that is the player clock and it needs steps 2–4 above. The self-test tells you which clock you are looking at in one command, by comparing the file's own generation date against your player's last-updated figure.

As for how often to schedule automatic refreshes: more often is not better. A guide regenerated twice a day gains nothing from being downloaded every hour, and on a low-powered device each refresh costs you a parsing pause. Once a day, overnight, suits most households.

Guide performance on low-powered devices

An EPG file scales with channels multiplied by days. A large lineup with a full week of listings is a substantial document, and your player has to download it, decompress it, parse it, and index it into something it can draw quickly. On an Apple TV or a Shield this is unremarkable. On a budget stick with limited memory it is the heaviest thing the app does all day.

The symptoms are recognisable once you know them: the player becomes unresponsive for a stretch shortly after a refresh, channel changes feel sluggish for the first minute after startup, or the app closes itself during an update. That is resource pressure, not corruption, and clearing the cache repeatedly will not help.

The levers that do help:

• Reduce the number of days loaded. If you never look beyond tomorrow, a seven-day window is costing you memory for nothing. This is the single most effective change.
• Trim the channel list. Hiding groups you never watch reduces what has to be held and drawn, in players that let you.
• Refresh overnight. Move the automatic update outside your viewing hours so the parsing pause happens while nobody is watching.
• Consider the device. If a stick is struggling with the guide, it is usually struggling with 4K decoding too. The device guide covers what handles a full lineup comfortably.

How to judge a provider's EPG before you commit

Channel counts are advertised everywhere; guide quality is advertised nowhere, which makes it a useful thing to check yourself. If you are trialling a service, these are worth ten minutes:

• How many days does the guide carry? Ask, then verify in the player rather than taking the number on the page.
• Do the channels you actually watch have listings? A guide can look complete on major networks and be empty on exactly the regional sports channel you subscribed for. Check your real list, not the front page.
• Is there more than a title? Descriptions, episode numbers and artwork are the difference between a guide you use and a grid you tolerate.
• Does catch-up line up with the guide? Scroll back and confirm that replay windows exist where the listings say they should.
• Spot-check the times. Pick two channels and compare against the broadcaster's own published schedule. This catches offset problems that look fine in isolation.
• Report one missing channel and see what happens. How a provider handles a specific, well-described ID mismatch tells you more about the service than any feature list.

For reference on the last point: IPTV Americans ships a full seven-day guide with catch-up on every package, and channel-level guide reports go to the same round-the-clock support as everything else.

What you cannot fix from the player

Some EPG problems are genuinely upstream, and recognising them saves an evening:

• A channel with no guide data being collected at source — no player setting creates data that does not exist.
• Wrong or generic programme titles coming from the broadcaster's own feed.
• Regional variants of a network sharing one guide, so the listings are right for a different feed than the one you are watching.
• Late sports scheduling, where a fixture moves after the guide was generated.
• A source file that omits timezone offsets, leaving every player to guess.

When you report one, four details turn a vague ticket into a fixable one: the exact channel name as it appears in your list, the player you are using, your time zone, and whether the listing is missing entirely or merely wrong. That is enough to reproduce it. Our support channels are staffed around the clock, and channel-level reports follow the same pattern.

Quick reference: EPG terms in one place

Frequently asked