IPTV 4K Server › Guide

Channels Play but the TV Guide Is Empty (or Hours Off)

Why the guide fails on its own

Video and the TV guide are two different downloads, and that single fact explains almost everything about this problem.

Streams are fetched one channel at a time, on demand, only while you are watching. The guide is one XMLTV file — often several megabytes, sometimes tens — pulled from a completely different endpoint on a schedule, usually every few hours. They share a host and a set of credentials, and nothing else.

So a perfect picture proves nothing about the guide, and an empty guide proves nothing about your subscription. Reinstalling the app because the EPG is blank is treating one download as if it were the other.

Test the endpoint without your player

The guide lives at the same host and port as your line:

http://host:port/xmltv.php?username=USER&password=PASS

Some players fetch this automatically from your Xtream login; others want the URL pasted in as an external EPG source. Either way, open it in a browser on a phone or laptop. Two cautions, the same two as every browser test on this site: the address carries your password in clear text, so do not screenshot it or paste it to anyone; and if the address bar rewrites http to https, the test is invalid — the connection guide explains why.

This is the decision point of the whole article:

• A wall of XML. The file exists and your credentials can reach it. The fault is in your player — keep reading.
• An empty page, a tiny response, a timeout, or a login page. The guide is missing or broken on the provider's side. Nothing you change locally will help, and every setting you try from here is wasted time.

On an Xtream-style line the guide is served from the same host as your streams, so an empty xmltv.php can only be repopulated by the provider. That means a message to whoever you bought the line from, with the details in the last section.

Size and timeouts

A full multi-country guide can be tens of megabytes of XML, and it has to be downloaded and parsed before anything appears. Slow boxes and short player timeouts abandon the download partway and then show you nothing at all, with no error message — which is why this looks like an outage rather than a failed fetch.

What to do, in order:

• Force a manual EPG refresh rather than waiting for the schedule, and give it several minutes without leaving the screen.
• Retry on a better connection — a wired box will finish a download that a marginal Wi-Fi link keeps dropping.
• Use a player that fetches the guide in parts, or that lets you limit which groups it loads.
• Hide channel groups you never watch, if your player supports it. A smaller guide is a guide that finishes downloading.

Caching, and why yesterday's failure is still on screen

Players store the guide locally and refresh it every few hours. If one fetch failed, many players keep showing the empty or stale result until the next scheduled attempt — so you can fix the underlying problem and see no change for hours.

Clear the EPG cache, or force a refresh. In most TV players this sits under the playlist or EPG settings, often as "update EPG", "refresh guide" or "clear EPG data". Reinstalling the app is the blunt version of the same step, which is why it occasionally appears to work — the cache went with it.

Wrong times: the common non-empty failure

XMLTV timestamps carry a timezone offset, like 20260906143000 +0000. If your guide is populated but every programme is out by a whole number of hours, that is an offset problem, not a broken guide, and a time-shift setting in your player corrects it from your end.

Measure the error first, with a direction and not just a size. Find a programme whose real start time you know, and write down both times — say it really starts at 20:00 and the guide shows it at 17:00, so the guide is running three hours early and its times need three hours added. Then check three things, in this order:

1. The device's timezone and automatic-time setting. Cheap Android boxes can ship set to the wrong region, or to UTC. Fix this first, because it also breaks recordings and reminders.
2. The player's own EPG time-shift setting. Most IPTV players have one, in hours, and it is applied to the times in the guide file. For the example above — guide three hours early, three hours to add — that is +3. Apply it, then check the same programme again: players are not consistent about which direction the number means, so if the times moved further the wrong way, use the opposite sign. What you must not do is guess the sign and then guess again at a bigger number; one correct step fixes it, and a wrong one doubles the error.
3. Daylight saving. An error that appeared overnight in spring or autumn, and is exactly one hour, is a DST handling problem — on the device, in the player, or in the file.

Do not fix a guide offset by changing the device clock to the wrong timezone. It works until it doesn't, and it breaks everything else that uses the time.

Guide on some channels, missing on others

This is ID mapping. Each channel in your playlist carries a tvg-id, and the XMLTV file lists programmes against channel ids of its own. Where the two match, you get a guide; where they do not, that channel shows blank while its neighbours are fine.

What you can fix: several players let you map a channel to a guide id by hand, so if the entry exists in the file under a different id, you can point at it. What you cannot fix: a channel that simply is not in the provider's XMLTV file. There is no id to map to, and no local setting invents one.

Guide loads but shows the wrong programmes

The channel is mapped to a different regional feed — a national guide against a regional variant, or the wrong country's version of the same brand. That mapping lives on the provider's side. Report it with the channel name rather than trying to correct it locally, because a manual override will be overwritten at the next update.

Why catch-up disappears with the guide

Archive and catch-up playback is addressed by programme start time: the player asks for the block that began at a particular moment on a particular channel. With no EPG entry, there is no start time to ask for, so the catch-up button has nothing to offer and disappears.

Readers usually report this as a second, separate fault. It is not — fix the guide and catch-up returns.

Yours or theirs

When it is theirs, send: the channel name, the guide id if your player displays it, a photo of the wrong times next to the correct ones, and — most importantly — whether xmltv.php returned anything in a browser. Send your username if they need to find the line; never your password, and never a screenshot of a browser tab that has it in the address bar. That last line about xmltv.php is the one that gets it looked at quickly.

If video is stalling as well as the guide, that is a separate problem: start with the buffering guide. If nothing plays at all, go to reading the connection error.