Where the codes appear
A chip is an icon in the bottom-left corner of the screen, with a one-line message when it first appears. The Player shows the highest-ranked active condition and keeps the chip while the condition holds. The dashboard shows the chip beside the screen's online state.
screenrig screen show scr_ID returns what the Player reported:
| Member | Holds |
|---|---|
status | chip, the chip's id (null when none shows), its level and when the Player reported it. Absent until the first report |
last_page_failure | page_id, code and at of the latest page that could not become ready |
manifest_upgrade | How the latest content update is going: state, code, attempt and retry_at |
storage, storage_shortfall | The Player's last storage report, and how far the playlist exceeds it. The shortfall is present only while content does not fit |
A chip is the Player's last report: read it as stale while online is false. Reports such as player.video_unusable and player.card_failed go to the screen's Player log:
screenrig events list --source log --screen-id scr_IDStatus chips
The table runs in rank order: when several conditions hold, the first one shows. The label is the chip's name in the dashboard.
| Chip | Cause | Fix |
|---|---|---|
archived (Screen archived) | The screen is archived, so its glass is dark. The Player keeps its credentials | screenrig screen unarchive scr_ID. The Player resumes without pairing again. A screen archived as replaced cannot be unarchived: screen delete removes it |
repair_needed (Needs repair) | The device key no longer binds the Player to its screen (credential_revoked, key_retired), or the device could not keep its identity. The Player keeps its saved content and its key | Reset the Player on the device: open its operator menu, choose Settings, then Reset. It gets a new pairing code: give the code to your agent |
payment_required (Usage out) | The project's usage credit is used up, so new content cannot reach the screen. From 1 January 2027 a remaining credit of zero or less also shows this chip | screenrig billing balance shows what is left. Add usage credit, as Pricing describes |
session_revoked (Connection ended) | The Player's credential was rejected or revoked, or its screen was deleted, while the Player holds saved content. It keeps playing that content and retries | Confirm the screen exists with screenrig screen show scr_ID. If the chip stays, reset the Player in its operator menu and pair it again |
verify_fail (Cannot verify) | A downloaded file failed its size, hash or type check, so the Player does not use it and keeps what it has. The update code is hash_mismatch | screenrig screen clear-cache scr_ID makes the Player download its content again |
storage_full (Storage full) | The device has no room for the content it must download, so new content cannot be saved | Free storage on the device or shrink the playlist. Cache and storage explains the fit |
decode_unplayable (Nothing plays) | The Player cannot play any item it has to show, and nothing else is on screen | Video that does not play. A Raspberry Pi 5 needs video uploaded with --codec hevc |
unavailable (Cannot show) | The Player has no saved content, its assignment did not resolve, and no more specific condition applies | Read manifest_upgrade and last_page_failure in screen show, fix what they name, then screenrig screen reload scr_ID |
browser_unsupported (Unsupported browser) | The browser that runs the web Player is unsupported. Playback continues | Update the browser |
app_unsupported (Unsupported app) | The screenRIG app version is unsupported. Playback continues | screenrig screen update-software scr_ID where the Player declares update, otherwise update through its store or device manager |
browser_warning (Browser warning) | The browser that runs the web Player is out of date. Playback continues | Update the browser |
app_warning (App warning) | The screenRIG app version is out of date. Playback continues | screenrig screen update-software scr_ID where the Player declares update, otherwise update through its store or device manager |
assignment_held (Update delayed) | The latest update is retrying or failed, or renewing the Player's session has taken more than 10 seconds. The current content keeps playing | Read manifest_upgrade in screen show. Page and update failures explains each state and code |
decode_miss (Item skipped) | One item cannot be played, so the Player skips it while other content plays | Video that does not play |
offline_playing (Playing offline) | Content is on screen and the Player has had no connection to screenRIG for 60 seconds or more. It plays its saved content | Restore the device's network. screen show reports last_outage and its likely_cause |
schedule_timezone (Needs timezone) | A page has a visibility schedule and the screen has no timezone, so the Player ignores the schedule and always shows the page | screenrig screen update scr_ID --timezone America/Los_Angeles, with the screen's IANA zone |
credits_low (Usage low) | Remaining usage credit is above zero and below 1,000 credits. Until 1 January 2027 remaining credit is not a shutoff instruction | screenrig billing balance shows what is left |
content_partial (Partial content) | Only part of the playlist plays: manifest_upgrade.state is partial and missing_page_count says how many pages are left out | Read manifest_upgrade.code: Cache and storage for capacity, Page and update failures for the rest |
paused (Paused) | Someone paused the screen on the device. A pause ends by itself after 60 minutes | Press Play/Pause on the remote (K on Windows) |
syncing (Updating) | The Player is downloading, preparing or activating new content, or renewing its session | None. The chip clears when the content is on screen. If it stays, read manifest_upgrade.state |
Player update required is a notice beside the chip, not a chip. It shows when the Player's version is below the minimum screenRIG supports, and the Player keeps playing its saved content. Update the Player with screenrig screen update-software scr_ID where it declares update, otherwise through its store or device manager.
Video that does not play
A Player decodes video with the device's hardware decoder for the file's codec, profile and resolution. When the device cannot, the Player skips the item: the chip is decode_miss, or decode_unplayable when nothing else is on screen. The Player log's player.video_unusable record names the code (video_load_failed, video_play_failed, video_autoplay_blocked, video_stalled, image_load_failed, video_prepare_failed, video_first_frame_timeout or video_decode_failed) with the decoder, codecs, width and height the Player measured.
screenrig media upload ./lobby-loop.mp4 --codec hevc
screenrig media upload ./lobby-loop.mp4 --preset signage-1080p30A video uploads as H.264 by default. A Raspberry Pi 5 has no H.264 decoder: upload every video for it with --codec hevc, at any size. A Raspberry Pi 4 plays 1080p, and --preset signage-1080p30 bounds the size. Use hevc only when every screen that plays the clip is a native Player. Replace the media in the playlist and publish it again.
Assigning a playlist whose video is all H.264 to a screen whose Player declares video.h264_unavailable is refused with invalid_request. In mixed content that Player skips the H.264 items.
Page and update failures
A page that cannot become ready is skipped and the Player keeps playing its other pages. It reports the failure, and last_page_failure.code is the Player's own code. screenrig events list --type playback.page_failed --screen-id scr_ID lists them.
| Code | Cause | Fix |
|---|---|---|
gstreamer_playback_error | The Linux or Raspberry Pi Player's media pipeline failed on a video: it reported an error, would not start, or produced no picture | Video that does not play |
unsupported_content | The playlist holds content the Player cannot present, a primitive or media type it does not support | See Primitive support by platform. Replace the content, or assign the playlist to a Player that supports it |
manifest_upgrade.state says how a content update is going:
| State | Meaning |
|---|---|
pending | screenRIG has new content for the screen and the Player has not reported on it |
downloading, preparing, activating | The update is under way. With content on screen the chip is syncing |
retrying | A step failed and the Player tries again at retry_at. The chip is assignment_held |
failed | The update stopped with no retry scheduled. The chip is assignment_held |
blocked | Storage cannot stage the new content. The chip is storage_full |
partial | Only part of the playlist plays. The chip is content_partial |
current | The newest content is playing |
manifest_upgrade.code names the cause of a retrying, failed, blocked or partial state:
| Code | Cause | Fix |
|---|---|---|
download_failed | A content download failed: the content origin was unreachable or answered an error | Check the device's connection. The Player retries on a backoff, and retry_at says when |
hash_mismatch | A downloaded file failed its size, hash or type check | screenrig screen clear-cache scr_ID |
prepare_failed | The Player could not prepare a page for display, or the page was not ready in time | Read last_page_failure and fix the page as its code says |
activate_failed | The first page of the new content could not be shown | Read last_page_failure, then screenrig screen reload scr_ID |
manifest_invalid | The Player rejected the revision's manifest as invalid and keeps its last good content. It does not retry that revision | Report it with the screen id at Contact |
unsupported_content | The Player dropped content it cannot present. With nothing playable left the update fails and is not retried; otherwise it is partial | As the page failure unsupported_content above |
internal | A Player error outside the codes above | screenrig screen reload scr_ID. If the code stays, report it with the screen id |
capacity, staged, storage_full, none_fit, transition_blocked, anchor_unavailable | The device's storage plan | Cache and storage |
Cache and storage
Before it downloads a revision, a Player plans its storage: which pages' files fit the space it may use. A native Player leaves 128 MiB of its volume free and stays within any quota set for it. At start, a Player with less than 512 MiB free shows a message with the free space; that message is not a chip.
storage.plan.fit in screen show says how the playlist fits:
fit | Meaning | Fix |
|---|---|---|
fits | The whole playlist fits | None |
fits_after_eviction, retention_reduced | The playlist fits after the Player drops cached files it no longer needs and, for retention_reduced, its saved fallback content | None. No page is left out |
partial | Some pages do not fit and are left out (excluded_pages). The rest plays | Free storage or shrink the playlist |
transition_blocked | The new playlist's always-visible page, the first page without a visibility schedule, cannot be stored beside the content on screen. The update waits, the current content keeps playing and headroom_needed_bytes says how much more room it needs | Free that much storage or shrink the new playlist |
none_fit | Nothing loads: no page fits, or the playlist has no always-visible page that fits | Free storage, or assign a smaller playlist |
manifest_upgrade.code repeats the plan: none_fit or transition_blocked for a blocked update, capacity for a partial update whose pages did not fit, staged for a partial update that is still filling, and storage_full when a write fails. storage_shortfall is present while fit is partial, transition_blocked or none_fit.
Each entry of excluded_pages has a reason:
| Reason | Cause | Fix |
|---|---|---|
object_exceeds_capacity | One file alone does not fit the space the Player may use | Upload it smaller (media upload --max-edge or --preset signage-1080p30), or use a device with more storage |
page_exceeds_capacity | Each file fits alone, but the page's files together do not | Put fewer or smaller files on the page |
capacity_excluded | The page was left out so the rest could fit | Free storage or shrink the playlist |
descriptor_conflict | The playlist lists one file twice with different sizes or content types | Report it with the screen id at Contact |
not_local | The Player restored saved content at start with no stored plan, and this page's files were not on the device | Bring the Player online: it downloads the page |
anchor_unavailable | The always-visible page failed to download although the device has room. That is a failed download, not a shortfall | Check the device's connection. The Player retries |
Ask before you assign a large playlist:
screenrig screen storage-forecast scr_ID --playlist-id pl_IDIt answers fits, partial, none_fit or unknown, with the bytes the playlist needs and the Player's capacity. unknown means the screen has never reported storage. A report older than 24 hours is marked stale. The command writes nothing. When a storage failure shows, the answer carries a storage_full warning: free storage on the device that runs the Player, then retry the playlist.
Cards
A card that cannot draw leaves its rectangle empty and the page plays on. The Player logs card.failed, and the web, Android and Windows Players report player.card_failed once for each card on a page and code, with page_id, primitive_id, manifest_revision and the code. A card whose data expired is blank too: screenrig card data put --ttl 30m renews it.
| Code | Cause | Fix |
|---|---|---|
unknown-card | The card id is not in the Player's cards library | Use a card from the card reference |
card-unavailable | The card is in the library, but this Player build does not carry it, or carries another major version than the page names | Update the Player, or place the major version it carries |
card-error | The card threw while drawing (web Player). The details are in the browser console | Check the card's properties against its reference page |
data-unavailable | The card's first data document did not arrive. The card stays hidden | screenrig card data put to write the data, or screenrig source show to check its data source |
data-source-missing | A card names card data and the Player has no data source for it | Report it with the screen and card ids at Contact |
cardml-invalid | A CardML card's file failed its checks | Report it with the card id at Contact |
cardml-model-error, cardml-model-timeout | A CardML card's model failed or ran past its time budget | Check the card's data and properties |
cardml-duplicate-key | A list in a CardML card met one key twice. It keeps its previous rows | Give each row its own key |
qr-too-long, wifi-too-long | The QR payload or the Wi-Fi details do not fit a QR code | Shorten the URL or the text |
invalid-target | A countdown's target does not parse | Set target to a valid date and time |