Skip to content

Troubleshooting

Jump to bottom
Gibson Bell edited this page Jul 14, 2026 · 5 revisions

Troubleshooting

Start with the narrowest failing layer: server, network, pairing, content, manifest, playback, or Android capability.

Server does not open

Check containers:

docker compose   --env-file deploy/docker/.env   -f deploy/docker/compose.yml   ps

Check health and readiness:

curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/readyz

Read logs:

docker compose   --env-file deploy/docker/.env   -f deploy/docker/compose.yml   logs --tail=300 server postgres

Common causes:

  • missing or invalid POSTGRES_PASSWORD
  • PostgreSQL volume or permission failure
  • unwritable tilecast_data volume
  • FFmpeg or FFprobe readiness failure
  • port 8080 already in use
  • reverse proxy pointing to the wrong service

Browser login loops or fails behind HTTPS

Confirm:

TILECAST_PUBLIC_URL=https://the-exact-hostname.example.org
TILECAST_COOKIE_SECURE=true

The browser origin, proxy hostname, and configured public URL must agree.

Player cannot discover the server

Discovery is optional and may fail because of:

  • Docker bridge networking
  • different VLANs
  • guest Wi-Fi
  • AP or client isolation
  • multicast filtering
  • routed networks

Enter the server URL manually.

Player rejects the server URL

Public hostnames require HTTPS. Plain HTTP is accepted only for private, link-local, localhost, and .local destinations.

Do not replace an HTTPS URL with HTTP to work around a certificate or proxy problem. Fix HTTPS.

Pairing code is not found

  • Codes expire after ten minutes.
  • Confirm all six characters.
  • Create a new request on the TV.
  • Confirm the browser is on the same Tilecast installation.
  • Check that an access gateway is not blocking player API requests.

Previously paired player asks to pair again

Review the request before deleting anything.

If Studio recognizes the stable installation ID, use Repair and replace credential. This preserves assignments and revokes the old credential only after successful enrollment.

Screen is Offline, Stale, or Recently online

  • Recently online: last contact within two minutes
  • Stale: more than two and no more than fifteen minutes
  • Offline: more than fifteen minutes

Check:

  • TV and player power
  • Wi-Fi association
  • DNS
  • server reachability from the TV network
  • reverse-proxy WebSocket support
  • changed Wi-Fi credentials
  • captive portal
  • Android background restrictions
  • server logs

Cached playback can continue even while Studio reports a connectivity problem.

Media remains Waiting or Processing

Check /readyz, free disk space, and server logs.

Open the asset to view its error. Failed items can be retried after correcting the underlying problem.

Large video files may need substantial temporary free space during processing.

Website Source does not load

Check:

  1. The URL works on another device on the same network.
  2. Public URLs use HTTPS.
  3. Private HTTP is enabled only when intentionally allowed by the server administrator.
  4. The top-level navigation host is allowed.
  5. JavaScript, DOM storage, and cookie policy match the site.
  6. The load timeout is long enough.
  7. The site does not require credentials Tilecast does not store.
  8. A fallback image or safe failure behavior is configured.

The server validates Website configuration but does not fetch the page on behalf of the player. A page can be valid yet unreachable from the TV network.

YouTube Source fails

  • Confirm the TV network can reach YouTube and the embedded player.
  • Confirm the URL is a supported video or playlist URL.
  • Check start and end values.
  • Try the placeholder or fallback image behavior.
  • Remember that YouTube is streamed and is unavailable offline.

Wrong playlist is showing

Check in this order:

  1. Active emergency
  2. Winning schedule
  3. Direct fallback assignment
  4. Manifest synchronization state

For schedule conflicts, check priority, direct versus group targeting, effective start, timezone, enabled state, and device clock skew.

New content never activates

A pending downloaded manifest does not activate until every required file passes size and SHA-256 verification.

Check:

  • player storage
  • cache limit
  • minimum free-space policy
  • media delivery endpoint
  • network interruption
  • failed content items
  • manifest error shown in Studio

The old working manifest should remain active.

Managed Kiosk requested but not active

Requested policy is not proof of capability.

Managed Kiosk requires compatible device-owner/device-policy provisioning and confirmed lock task. Consumer Fire TV firmware may not support it.

Accessibility Control requested but not active

Enable the service manually in Android Accessibility Settings on that player. Server policy cannot grant the permission.

TV stays on outside active hours

Tilecast may only be able to show black. It does not send direct HDMI-CEC commands.

Review the reported sleep strategy and the per-screen physical Power Assist test.

Player enters safe mode

Use the local maintenance sequence:

Back, Back, Up, Down, Select

Enter the maintenance PIN, review self-test and recovery state, then retry or exit safe mode after correcting the failure.

Owners and Administrators can also use typed recovery and synchronization commands from Studio.

Update waits for permission or user

On the TV, allow Tilecast Player under Install unknown apps, then approve the Android or Fire OS system installer.

These states are expected. Tilecast does not claim silent installation.

Still stuck

Collect the information listed in Support and Contributing without including credentials, tokens, signing keys, or private URLs.

Tilecast repository · Issues · Technical documentation

Tilecast Wiki

Home

Get started

Build playback

Operate players

Maintain Tilecast

Project

Clone this wiki locally