# Realtime collaboration diagnostics

<!-- Generated by docs/modules/diagnostics from the package catalogs. Write a guide in docs/diagnostics/<CODE>.md instead of editing this file. -->

Each Realtime collaboration error has a stable `code`. Its `docs` link opens the page of that code. This page lists all 33 codes, and [All diagnostics](https://vitehub.dev/docs/reference/diagnostics) lists every primitive.

## Configuration errors

| Code | What happened |
| --- | --- |
| [`REALTIME_BLOB_ETAG_MISSING`](https://vitehub.dev/docs/realtime/diagnostics/realtime_blob_etag_missing) | The Blob store returned no `httpEtag` for \<pathname\>, so `blobDocument()` cannot save the file only if it is unchanged. |
| [`REALTIME_CHECKPOINT_UNSUPPORTED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_checkpoint_unsupported) | The Realtime definition sets `history.checkpoint`, but its document adapter has no `checkpoint()` method, so `history.checkpoint()` could never run. |
| [`REALTIME_INVALID_ACCESS`](https://vitehub.dev/docs/realtime/diagnostics/realtime_invalid_access) | The Realtime definition sets `origins()` with `auth: true` and no `identify()`. The ViteHub Auth session is a cookie, so ViteHub accepts it only from the app's own origin. |
| [`REALTIME_INVALID_PERSISTENCE`](https://vitehub.dev/docs/realtime/diagnostics/realtime_invalid_persistence) | Realtime `persistence.<name>` must be a non-negative number of milliseconds. |
| [`REALTIME_INVALID_POSTGRES_URL`](https://vitehub.dev/docs/realtime/diagnostics/realtime_invalid_postgres_url) | REALTIME_POSTGRES_URL is set, and it is not a `postgres://` or `postgresql://` URL. |
| [`REALTIME_INVALID_USER`](https://vitehub.dev/docs/realtime/diagnostics/realtime_invalid_user) | The realtime identity needs a user `id` that is a non-empty string of at most 256 characters. |
| [`REALTIME_MISSING_ACCESS`](https://vitehub.dev/docs/realtime/diagnostics/realtime_missing_access) | The Realtime definition sets no access rule, so it does not say who can read and write its rooms. |
| [`REALTIME_MISSING_BUS_CONNECTION`](https://vitehub.dev/docs/realtime/diagnostics/realtime_missing_bus_connection) | Realtime driver "postgres" shares rooms through Postgres, and the app has no Postgres Default Database and no REALTIME_POSTGRES_URL. |
| [`REALTIME_MISSING_DIGEST`](https://vitehub.dev/docs/realtime/diagnostics/realtime_missing_digest) | Realtime saves need Workspace file digests, and the Workspace Store did not return one. |
| [`REALTIME_ROOM_LOCK_TIMEOUT`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_lock_timeout) | Realtime waited 30 seconds for the save lock of a room, and another instance still holds it. |

## Build errors

| Code | What happened |
| --- | --- |
| [`REALTIME_DRIVER_CONFLICT`](https://vitehub.dev/docs/realtime/diagnostics/realtime_driver_conflict) | Realtime driver "\<driver\>" needs a Node.js server, and the \<host\> host does not run one. |
| [`REALTIME_MISSING_DRIVER`](https://vitehub.dev/docs/realtime/diagnostics/realtime_missing_driver) | Realtime production builds need one room driver, and ViteHub cannot select one for this deployment. |
| [`REALTIME_RENAMED_AUTHORITY_KEY`](https://vitehub.dev/docs/realtime/diagnostics/realtime_renamed_authority_key) | `realtime.authority` is \<value\>. ViteHub renamed this key to `driver`, and it does not read `authority`, so Realtime would not use the driver you chose. |

## Room errors

| Code | What happened |
| --- | --- |
| [`REALTIME_AWARENESS_OWNERSHIP_CONFLICT`](https://vitehub.dev/docs/realtime/diagnostics/realtime_awareness_ownership_conflict) | A realtime awareness client id belongs to another peer. |
| [`REALTIME_AWARENESS_TOO_LARGE`](https://vitehub.dev/docs/realtime/diagnostics/realtime_awareness_too_large) | Realtime awareness state exceeds the 8 MiB room quota. |
| [`REALTIME_DOCUMENT_TOO_LARGE`](https://vitehub.dev/docs/realtime/diagnostics/realtime_document_too_large) | The realtime document exceeds the 8 MiB room quota. |
| [`REALTIME_INVALID_AWARENESS`](https://vitehub.dev/docs/realtime/diagnostics/realtime_invalid_awareness) | A realtime awareness update has a state that is not a plain object. |
| [`REALTIME_TOO_MANY_AWARENESS_CLIENTS`](https://vitehub.dev/docs/realtime/diagnostics/realtime_too_many_awareness_clients) | One realtime peer sent more than 1,024 awareness clients. |

## Client errors

| Code | What happened |
| --- | --- |
| [`REALTIME_DISABLED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_disabled) | Realtime is disabled, so `<action>()` cannot run. |
| [`REALTIME_DISCONNECTED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_disconnected) | The realtime document disconnected or changed during `<action>()`. |
| [`REALTIME_INVALID_RESPONSE`](https://vitehub.dev/docs/realtime/diagnostics/realtime_invalid_response) | The realtime server answered `<action>()` with a response that the client cannot use. |
| [`REALTIME_MISSING_DOCUMENT`](https://vitehub.dev/docs/realtime/diagnostics/realtime_missing_document) | `<action>()` needs a document, and `documentId` is empty. |
| [`REALTIME_REQUEST_FAILED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_request_failed) | The realtime `<action>()` request failed\<value\>\<value\> |

## Adapter errors

| Code | What happened |
| --- | --- |
| [`REALTIME_DOCUMENT_CONFLICT`](https://vitehub.dev/docs/realtime/diagnostics/realtime_document_conflict) | The stored document changed since the realtime room loaded it. |

## Room request errors

| Code | What happened |
| --- | --- |
| [`REALTIME_ROOM_ABORTED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_aborted) | The request to the room stopped because its signal aborted. |
| [`REALTIME_ROOM_CROWDED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_crowded) | \<count\> browsers are in the room, and a request goes to one browser only. |
| [`REALTIME_ROOM_ELSEWHERE`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_elsewhere) | No browser in this instance is in the room. With Redis or Postgres, the browser can be connected to another instance, and requests reach only the browsers of the same instance. |
| [`REALTIME_ROOM_EMPTY`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_empty) | No browser is in the room. The page is closed, or it has not joined yet. |
| [`REALTIME_ROOM_REFUSED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_refused) | The browser could not answer: \<reason\> |
| [`REALTIME_ROOM_REQUESTS_OFF`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_requests_off) | The Realtime Definition "\<definition\>" does not take requests. |
| [`REALTIME_ROOM_TIMEOUT`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_timeout) | The browser did not answer in \<value\> seconds. |

## Room write errors

| Code | What happened |
| --- | --- |
| [`REALTIME_ROOM_WRITE_CONFLICT`](https://vitehub.dev/docs/realtime/diagnostics/realtime_room_write_conflict) | Realtime room record compare-and-set failed. |
| [`REALTIME_WRITE_REJECTED`](https://vitehub.dev/docs/realtime/diagnostics/realtime_write_rejected) | Realtime update depends on state this room does not have. |

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/realtime.md)
- [Get started](https://vitehub.dev/raw/docs/realtime/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/realtime/configure.md)
- [Server API](https://vitehub.dev/raw/docs/realtime/server-api.md)
- [Limits and errors](https://vitehub.dev/raw/docs/realtime/limits-and-errors.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
