Troubleshooting
Fixes for the most common issues: content not updating, a screen limit message, video that won't play, panel placement and remote controls.
Most issues come down to one of three things: the network, the gallery code, or a plan limit. Work through the relevant section below.
The screen won't leave the welcome screen
After entering a code, the app fetches the gallery's manifest. If it stays on the welcome screen:
- Check the code. It should match the gallery's Connect tab exactly. Letters and numbers only, no dash.
- Check the network. The Apple TV must reach
getbillboard.appover HTTPS. See Network requirements. - Deploying by MDM? Confirm
dataURLis set tohttps://getbillboard.app/m/<CODE>and reached the device. See Jamf or Intune.
A "screen limit reached" message
This means more Apple TVs are live on your account than your plan allows. The earliest screens keep playing; the extras show this message.
- Raise your plan on the Billing page, and the waiting screens recover on their next check-in.
- Or free a slot by disconnecting a screen you're not using. A screen stops counting about 10 minutes after it last checked in.
Full detail: Plans, billing & screen limits.
Content isn't updating
Screens re-fetch on a schedule, so changes appear on the next check-in rather than instantly.
- By default a screen checks for updates every few minutes. You can set a gallery's Refresh interval in the dashboard, from every few minutes up to weekly.
- After you change media or settings, wait for the next check-in. The gallery page shows a countdown to it.
- Still stale after that? Confirm the Apple TV still has network access to
getbillboard.appand*.supabase.co.
Images or video won't play
- Blank or black slideshow. Media is served from
*.supabase.co; if that domain is blocked the content can't download. See Network requirements. - A video is skipped. Use
.mp4,.movor.m4v. Re-export anything in another format. - Video looks soft. Upload at Full HD (1920×1080) or higher. The dashboard warns you when a file is below Full HD.
- Video has no sound / doesn't play in full. These are per-gallery settings. Turn on play-with-audio or play-in-full in the gallery's settings.
The AirPlay panel is in the way
- The panel drifts around the screen on purpose, to prevent burn-in. You can change how it moves, hide it entirely, or hide it only during video, in the gallery's AirPlay settings.
- Hard to read over busy images? Set the opacity to Frosted, or add a brand tint. See Managing galleries.
Remote controls on the Apple TV
Billboard is locked down so it isn't closed by accident:
- Open on-device settings: press Play/Pause three times quickly.
- Exit the app: press Back/Menu five times quickly.
To stop anyone exiting at all, lock the device with Single App Mode.
The screen goes to sleep
Billboard keeps the display awake while it's running and resumes on its own after a restart. If the TV still sleeps, check the Apple TV's own Settings → General → Sleep and any screen-saver or HDMI-CEC power settings on the display.
Still stuck?
Email us at support@getbillboard.app with your gallery code and a photo of the screen, and we'll help.