# Player status codes

> Canonical HTML: https://screenrig.ai/docs/troubleshooting

A Player shows one status chip when something needs attention and reports the condition to screenRIG. This page lists each chip, and each page, update, storage and card code, with its usual cause and its fix.

## 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:

```sh
screenrig events list --source log --screen-id scr_ID
```

## Status 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](https://screenrig.ai/pricing.md#credits) 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](#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](#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](#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](#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](#cache-and-storage) for `capacity`, [Page and update failures](#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.

```sh
screenrig media upload ./lobby-loop.mp4 --codec hevc
screenrig media upload ./lobby-loop.mp4 --preset signage-1080p30
```

A 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](#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](https://screenrig.ai/docs/players.md#primitive-support). 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](https://screenrig.ai/contact.md) |
| `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) |

## 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](https://screenrig.ai/contact.md) |
| `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:

```sh
screenrig screen storage-forecast scr_ID --playlist-id pl_ID
```

It 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](https://screenrig.ai/docs/cards.md) |
| `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](https://screenrig.ai/contact.md) |
| `cardml-invalid` | A CardML card's file failed its checks | Report it with the card id at [Contact](https://screenrig.ai/contact.md) |
| `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 |