When something doesn’t work, walk this tree top-to-bottom. Most issues resolve in step 1 or 2.
Step 1 — Force-quit the app
webOS keeps apps suspended in memory. A bad state survives an exit. Fully kill it:
- Press the Home button on the remote.
- Highlight the Lumen·TV tile in the recent apps row.
- Press the down arrow on the D-pad — a ”×” appears.
- Press OK to close.
Re-launch. If the issue is gone, it was a transient state. If it persists, continue.
Step 2 — Check the network
Settings → All settings → Network → Wi-Fi connection → IP info
Verify the TV has an IP, a gateway, and DNS. Then on a phone on the same network, browse to https://api.lumentv.app/health — should return {"ok":true,...}.
If the phone gets through but the TV cannot, the TV’s DNS is stale. Restart the router, then the TV.
Step 3 — Symptom-specific decision tree
“I paid but the TV is still locked”
| Sub-symptom | Cause | Fix |
|---|---|---|
| Paywall appears even though Stripe shows the payment | Webhook didn’t fire | Press the Refresh license button on the paywall. If still locked after 30s, contact support with your Stripe order ID. |
| Paywall appears, payment was on a different TV | Lifetime license is per device. | We can transfer it. Email support. |
| Paywall appears immediately on launch (never even tried trial) | Anti-spoof flagged a fingerprint mismatch | Possible if you replaced your TV’s MAC, factory-reset, or use a custom firmware. Email support — we can re-issue. |
“App boots, then crashes / black screen”
| Sub-symptom | Cause | Fix |
|---|---|---|
| Crash within 2 seconds of opening | Storage full or corrupted | Settings → Storage on TV, free 100 MB+. Reinstall Lumen if needed. |
| Black screen, audio plays | GPU compositor stuck | Power-cycle the TV (unplug 30s, plug back in). Soft reboot doesn’t always fix it. |
| Crash after 10–30 minutes of playback | Memory leak (we know about a couple, fix in v1.1) | Restart app every couple of hours as a workaround. Confirm by emailing us your TV model. |
“Channels load but nothing plays”
→ Most likely a codec issue. See Buffer tuning for the codec compatibility table.
→ Second most likely: provider blocks your UA. See Custom user-agent.
“EPG is empty”
→ Almost certainly a tvg-id mismatch. See Configure EPG (XMLTV) properly.
“Some channels fail with ‘Connection refused’”
| Sub-symptom | Cause | Fix |
|---|---|---|
| Specific channels, others fine | Channel URL is dead | Provider should fix. Test the URL in VLC. |
| All channels from one source | Provider IP-banned your home | Try a VPN or contact provider. |
| All channels everywhere | Network outage | Test other apps on the TV. If they work, the issue is provider-side. |
“Remote control feels laggy”
| Sub-symptom | Cause | Fix |
|---|---|---|
| Magic Remote pointer drifts | Calibration off | Hold OK + Settings together for 5s — recenters cursor. |
| D-pad navigation skips items | Spotlight focus race | Restart the app. Known on webOS 6.x with very long lists. |
| Audio out of sync after pause/resume | Stream-specific A/V drift | Stop and restart the channel. Some MPEG-TS streams ship broken PTS. |
Step 4 — Collect diagnostics before contacting us
If none of the above worked, we need:
- TV model (Settings → All settings → General → About → Model name).
- webOS version (same screen, “Software version”).
- Lumen version (Settings → About in the app).
- What you did — exact sequence of steps.
- What happened — error message, screenshot, screen recording if possible (
Settings → Software Updates → Developer Options → Screen recorder).
Email all of the above to support@lumentv.app. We answer within 24 hours weekdays.
What we won’t help with
- Configuring playlists from providers we know are illegal in your country (we don’t know which providers are legal where you are; that’s on you).
- Tinkering with rooted / jailbroken / firmware-modded TVs — webOS exfiltration is outside our support scope.
- “Why doesn’t the channel I watch on my friend’s TV play on mine?” — different streams, different TVs, different providers; not a Lumen issue.