Troubleshooting

Display stuck on setup screen

Symptoms: Player shows the CMS configuration form and never progresses to content.

Solutions:

• Verify the CMS URL is correct and includes https://
• Check the CMS Secret Key matches (Settings → Display Settings in CMS)
• Ensure the player can reach the CMS: curl -sf https://your-cms/api/about
• Check firewall rules — the CMS must be accessible from the player's network

Content not updating after schedule change

Symptoms: You changed the schedule in CMS but the player shows old content.

Solutions:

• Wait for the collection interval (default: 5 minutes)
• Send Collect Now from CMS → Displays → row menu → Send Command
• Check XMR is running — real-time commands require the XMR service
• Verify the schedule's date/time range includes the current time (check timezone)

Video not playing

Symptoms: Video widget shows a black rectangle or loading indicator.

Solutions:

• Check the video codec — MP4 with H.264 is universally supported
• For HLS streams, ensure the .m3u8 URL is accessible from the player
• Electron: verify GPU acceleration is enabled (--ignore-gpu-blocklist flag is default)
• Check browser console for CORS errors — videos must be served from the CMS or a CORS-enabled CDN
• Large videos: wait for the download to complete (check the download overlay with D key)

CMS connection refused / timeout

Symptoms: Player logs show "XMDS error", "fetch failed", or "ECONNREFUSED".

Solutions:

• Verify the CMS is running: curl https://your-cms/api/about
• Check DNS resolution from the player: nslookup your-cms.example.com
• Verify no firewall blocks port 443 (HTTPS) or 80 (HTTP)
• If using a self-signed certificate, set relaxSslCerts: true in config.json
• Check proxy settings if the player is behind a corporate proxy

Display shows as offline in CMS

Symptoms: CMS shows the display with a red status indicator.

Solutions:

• Check the player is running: systemctl --user status xiboplayer-electron
• Verify network connectivity from the player
• Check the collection interval — a display is "offline" if it hasn't checked in within 2x the interval
• Review player logs: journalctl --user -u xiboplayer-electron -f

Black screen after boot (kiosk)

Symptoms: Kiosk boots to a black screen, no player UI visible.

Solutions:

• Press Ctrl+I to show the status overlay (IP, CMS, player status)
• Check GDM is running: systemctl status gdm
• Verify the kiosk session is configured: cat /var/lib/AccountsService/users/xibo
• Check the player service: systemctl --user -M xibo@ status xibo-player.service
• Review the session log: journalctl --user -u gnome-kiosk-script -f

CORS errors in browser console

Symptoms: Console shows "Access-Control-Allow-Origin" errors, resources fail to load.

Solutions:

• PWA: Must be served from the same origin as the CMS, or use the proxy
• Electron/Chromium: The built-in proxy handles CORS automatically — this should not happen
• Check that the proxy server is running on the expected port (8765 for Electron, 8766 for Chromium)
• If using a reverse proxy (nginx/SWAG), ensure it passes CORS headers

Schedule not appearing at correct times

Symptoms: Content shows at wrong times or not at all during scheduled periods.

Solutions:

• Verify the player's timezone matches the CMS timezone
• Check the schedule's dayparting settings in CMS
• Campaign priority: higher-priority campaigns override lower ones
• Use the timeline overlay (T key in the player) to see what's scheduled

Player high CPU usage

Symptoms: CPU usage above 20% during normal playback.

Solutions:

• Electron: Ensure GPU acceleration is working — check chrome://gpu in dev mode
• Chromium: Verify --enable-gpu-rasterization and --enable-zero-copy flags are applied
• Check for complex layouts with many regions or heavy JavaScript widgets
• Review video resolution — 4K video on a 1080p display wastes resources
• Expected: 4-5% CPU in production with GPU acceleration enabled

Screenshots not submitting

Symptoms: CMS shows no screenshots for the display.

Solutions:

• Check screenshotInterval in display settings (CMS → Display Settings)
• Electron uses desktopCapturer API — requires a display
• Chromium falls back to html2canvas — check browser console for errors
• Verify the CMS can receive uploads — check PHP upload_max_filesize

XMR commands not received

Symptoms: Collect Now, screenshot, and other real-time commands don't work.

Solutions:

• Verify XMR is running on the CMS server
• Check the XMR public address is reachable from the player (default: port 9505)
• Review the player's XMR connection log for WebSocket errors
• Ensure the display's hardware key matches the registered key in CMS
• Restart the player to force a new XMR channel registration

Display registered but no content

Symptoms: Display is authorized in CMS but shows "No scheduled content" or the default layout.

Solutions:

• Create a campaign in CMS and schedule it for the display or its display group
• Check the schedule's date range includes today
• Verify the display is in the correct Display Group
• Send Collect Now to trigger an immediate schedule refresh
• Check the player's timeline overlay (T key) to see the current schedule