Troubleshoot Tilecast Edge

Start in Studio. Edge reports through the normal Screens, Activity, and Player updates pages, so check those before you open a shell on the computer.

Local status and logs

/opt/tilecast-edge/current/bin/tilecastctl status
journalctl -u tilecast-edge.service
journalctl -u tilecast-renderer.service

tilecastctl status shows pairing, the server connection, the renderer, safe mode, and recovery mode. The Player service and the renderer have separate logs, so you can tell a renderer crash from a Player problem. tilecastctl capabilities shows why a hardware feature is unavailable.

Common problems

No server found: enter the server address manually. LAN discovery is optional.
Presentation unavailable: the content needs something Edge can’t show, such as AirPlay Present, or it includes a Website or YouTube item while Edge’s web helper is unavailable. Check content compatibility and the capability matrix.
Live preview or Watch live shows a black area where a video plays: Edge normally captures what the display shows, so video is included. Look in the renderer log for preview: lines: journalctl -u tilecast-renderer.service | grep 'preview:'. using presented WPE buffer is the normal source. falling back to WebKit snapshot means Edge couldn’t read the display image, and the reason in brackets says why. A fallback image can leave out video. Playback itself isn’t affected.
Renderer keeps restarting: check Activity and safe mode before you delete any Player data.
The screen enters safe mode but the content looked fine: read the Player log for playback_stalled and heal_action lines before the first recovery step. They name the content kind, the reason, the item, and the Layout zone when one applies, so you can see what Edge was waiting for. Edge doesn’t treat a page, Widget, or Layout that stays unchanged as stalled. It recovers when a Layout zone that must keep updating stops, when a Website or zone never draws its first frame, or when a video stops advancing. Activity records the same reason on each recovery event. With the default reliability policy, the recovery supervisor waits three minutes without meaningful progress, then tries reactivate, reload renderer, and restart renderer, spacing actions by 90 seconds. Safe mode is entered only after the full ladder is exhausted three times inside one hour. Ten minutes of sustained healthy progress clears that recovery history. Player policy can change the configurable recovery values.
A Layout appears and later triggers recovery: Layout health is zone-aware. A new item gets 90 seconds to produce its first render. A Layout zone that declares ongoing rotation can be silent for up to five minutes before it is considered stalled; static zones owe their first render but do not need to keep changing. Video has a separate 20-second progress tolerance. These evidence windows decide when content is stalled; the recovery ladder then decides what action to take.

With the default reliability policy, video must show progress at least every 20 seconds, a new item has 90 seconds to produce its first render (a Website or Widget uses the Website stall threshold from Player policy instead, 45 seconds by default, and recovery does not start before that time passes), and a rotating Layout zone has five minutes between required render evidence. Once playback is considered stalled, the recovery supervisor waits for the configured playback-stall threshold — three minutes by default — then tries reactivate, reload renderer, and restart renderer, spacing actions by 90 seconds. Repeated exhaustion of the full ladder enters Safe Mode after three ladder runs within one hour by default. Ten minutes of sustained healthy progress clears the recovery history. The organization or screen Player policy can change the stall threshold, restart window, restart count, and whether Safe Mode is enabled.
Display Control unavailable: check the reason in tilecastctl capabilities, such as missing hardware, a missing permission, a disconnected display, no DDC/CI response, or an unsupported control. See Display Control troubleshooting.
Migration refused or rolled back: run sudo /opt/tilecast-edge/current/bin/tilecast-edge-migrate status for the reason, fix it, and migrate again. See Migrate. The reason starts with the layer that failed:
- drm_probe_failed means the display probe couldn’t run. The text after it says why, such as error while loading shared libraries. Check the requirements.
- drm_output_unavailable means the probe ran but found no connected display with a mode.
- self_test_failed: renderer_start_failed or renderer_exited means the test renderer didn’t start or stopped. The text after it has the exit status or signal and the last line it printed. A message that mentions bwrap points to missing bubblewrap or blocked user namespaces.
- self_test_failed: fixture_import_failed means the built-in test content couldn’t be stored, for example because the disk is full.

Updates

sudo /opt/tilecast-edge/current/bin/tilecast-edge-update status
journalctl -u tilecast-edge-update.service -u tilecast-edge-update-guard.service

status shows the installed releases, the current one, and the last update with its result and reason. Update Tilecast Edge explains each rollback reason. For deployment problems in Studio, see Player update troubleshooting.

If the screen shows its recovery screen after an update and tilecastctl status reports state_db_newer_schema, follow Recover after a rollback.

Leftover 0.2.0 workaround files

If you worked around Edge 0.2.0 by hand with edge-0.2.0-field-fix.conf files in /etc/systemd/system/*.service.d/, Edge 0.2.1 removes them for you after an update is confirmed, but only the exact files that the Tilecast field script wrote. To see what is there:

sudo /opt/tilecast-edge/current/bin/tilecast-edge-update overrides

A file at one of those paths that you edited stays where it is, and the command lists it as an unknown override. Edge 0.2.1 ignores WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS, so such a file can’t turn the web sandbox off.

What not to do

Don’t run tilecastd as root to work around a device permission.
Don’t delete /var/lib/tilecast-edge/ as a routine troubleshooting step. It holds the screen’s pairing and cached content.
Don’t post Player credentials, pairing secrets, or private state files in a public issue.