Skip to content

Error Codes realtime

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/realtime

Part of Error codes: every code @ultimat3/realtime registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_CHANNEL_CATCHUP_POLICY_MISMATCH a channel's catch-up read decides with another policy a channel('', { catchUp, policy }) declaration names a catch-up query whose policy is not the channel's own policy object. The query is served at GET /_x/query/ with the channel params as input, so a read with a wider policy (a bare can(':read') beside a channel rule comparing a param to the actor) hands any caller what the channel refuses edit the catch-up query file the cause names: set its policy: to the same object the channel() call passes as policy: (export the rule from the feature's policy.ts and import it in both)
X_CHANNEL_DECLARATION_INVALID a channel() declaration cannot route its rows a channel(name, { … }) declaration the cause names is refused. At declaration: a name outside the topic-segment charset, a param listed twice, a records entity that is not an entity() declaration, or a param that is not a column of every listed entity, so its rows would match no topic. At serve time: two declarations sharing one name (a channel name is its topic prefix), or an events publish on a channel declared without events: true edit the channel('<name>', …) declaration as the cause says. The cause and fix name the exact option
X_CURSOR_STALE the resume LSN is outside the change buffer a long disconnect resumeFrom(cursor, { source, snapshot }) — with snapshot, the fallback re-snapshots
X_DEVICE_FRAME_TOO_LARGE a device socket frame is over the framework frame limit a device sent, or a request tried to send, a frame larger than DEVICE_FRAME_MAX_BYTES import { DEVICE_FRAME_MAX_BYTES } from "@ultimat3/realtime/server" — then split the payload into frames under it, or move the bytes to storage and send a key
X_DEVICE_OFFLINE no socket is open for the device a request addressed the device is disconnected, is registered under another tenant, or the node holding it went away x doctor --json — then retry deviceLink.request(ctx, deviceId, frame) once the device redials, across replicas every role needs NATS_URL set (or one transport in apps//runtime.ts)
X_DEVICE_REQUEST_TIMEOUT a device did not answer a request before its deadline the device received the request frame and sent no response frame with its id in time deviceLink.request(ctx, deviceId, frame, { deadlineMs: 60_000 }) — a longer deadline, or answer every request frame with { t: 'response', id, frame } on the device
X_FRAME_RATE_LIMIT one socket sent frames faster than this node will route them the accept budget spends a token per upgrade, so an open socket was unbounded: one authenticated client could drive a database read, a shared-store presence write and a fleet-wide publish per frame. Every socket now carries its own token bucket (64/s, burst 256), checked at the top of the frame router before the frame touches anything — including before it renews the idle window. A client fault: it never pages anyone syncNode({ maxFramesPerSecond }) raised where the node is built (the fix: line doubles the cap), or batch subscribes into one frame per subscription and retry after the delay
X_LIVE_CLIENT_MISSING retired in 21.0.0 (no LiveClient to register; see X_REALTIME_UNINSTALLED): a realtime hook ran in a browser with no LiveClient registered registered, thrown by nothing since 21.0.0. There is no LiveClient to register: the island bootstrap installs realtime, and a hook in a bundle that never did is X_REALTIME_UNINSTALLED delete any branch matching this code, because it never runs. For the failure it used to name, see X_REALTIME_UNINSTALLED
X_LIVE_QUERY_UNKNOWN no live query is registered under the name a subscribe frame asked for a misspelled name, or a query never passed to defineApi({ queries }) — the frame parsed and the version matched, so this is not a protocol skew and a client rebuild cannot change it x queries list --json
X_LIVE_REPLICA_IDENTITY a replicated table has no replica identity an entity table with no primary key under REPLICA IDENTITY DEFAULT, or with REPLICA IDENTITY NOTHING: once published, Postgres refuses its UPDATE and DELETE and a change cannot be keyed. A table with a primary key is never named (22.1.0; until then every non-FULL table was, on every boot). Warned at preflight, never thrown ALTER TABLE <t> REPLICA IDENTITY FULL; or a primary key — one per table the warning names; rows already in the WAL keep the identity they were written with
X_LIVE_ROW_UNIDENTIFIED a live query returned a row with no id a live: true read whose projection selects columns but not the primary key — patches, cursors and the local store all address a row by a text id — or whose id is neither text nor a safe integer (an integer key is sent as text, as the change feed sends it) x queries show <name> --json — select the primary key in that query's sql(), or drop live: true from it; for an id of another type, project the key as text
X_LIVE_SERVER_RENDER a browser-only live operation ran during a server render a useMutation() call reached from a page body. A server render has no socket and no page store, and a dropped write would look exactly like one that happened, so it refuses rather than queues x g island <route-dir> --at <route-dir> — move the call into the island's event handler. Guarding it with hasPageSocket() is not a fix: on the server that answers false forever, and the budgets step reports it as X_LIVE_ROUTE_NO_ISLAND
X_LOCAL_STORE_UNAVAILABLE the page's durable store could not open IndexedDB is blocked or absent (a private window, storage disabled, a runtime with no indexedDB), so persisted records and queued writes live in memory and are lost on reload. A warning, never thrown: console.warn once, and the page carries on, because a page never breaks for being unable to remember. 21.0.0 nothing to do in the app. Allow site storage in the browser (a private window blocks it) and reload
X_MUTATION_PATH_UNFILLED a pinned action's :param had no value in the write's input useMutation or the outbox replay was handed an input with no usable value for a :param of the action's http.path pin, so no URL could be filled — the write was not sent pass the param in the mutation's input: mutate({ <param>: '<value>', ... }), the key the pin's :<param> names
X_OFFLINE_QUEUE_ABANDONED a write was queued after its page changed principal a write reached OfflineQueue.enqueue() on a queue abandon() had already ended — the page moved to another principal (a sign-out, a sign-in as someone else) while the write was being queued. It was NOT stored and will never be sent: a write issued under one session must not leave under the next. Raised to the caller so the loss is never silent; call the mutation again under the current session x errors explain X_OFFLINE_QUEUE_ABANDONED --json
X_OFFLINE_QUEUE_FULL the offline queue is full a write was made while the page held as many unsent writes as its offline queue allows (maxQueued); it was refused rather than any queued write dropped OfflineQueue.open(store, { maxQueued }) — raise the ceiling, or let the page reconnect so the queue drains
X_PROTOCOL_VERSION client and sync node disagree on the wire protocol a client from an older build x build and redeploy the client; the node sends update-available before draining
X_QUERY_NOT_SUBSCRIBABLE retired in 21.0.0 (liveHookFor was deleted; useQuery reads any query): a hook was bound to a query that is not declared live registered, thrown by nothing since 21.0.0. liveHookFor is deleted, and useQuery reads a live and a non-live query alike: live-ness is on the declaration delete any branch matching this code, because it never runs. Use useQuery({ name, live: true }, input)
X_REALTIME_PRODUCER_CONFLICT two kinds of producer carry one table on the change bus a table the WAL replicator already carries is also published by a recordPublisher (or the reverse), so every committed row would reach its channels twice; the sync node keeps the producer kind it saw first and drops the other recordPublisher({ entities: [/* every entity but this table's */] }) where the replicator runs — it already carries every committed row — then restart the sync node
X_REALTIME_TOPOLOGY a sync node boots on a real database with no reachable change feed role sync on an external database, with the in-process transport and no replicator in this process: the replicator in another pod publishes into its own in-process bus, and every live query and channel here is silent with no error. Raised only when the node serves something that reads a change — a live: true query, or a channel that lists records; a node whose channels are events-only needs no replicator on any transport (27.5.0) export NATS_URL=nats://<host>:4222 for every realtime role (web, sync, replicator) — or, for a bus of your own, add transport: myTransport to export const runtime = { … } in apps//runtime.ts — or run the replicator in this process: x dev --role sync,replicator
X_REALTIME_UNINSTALLED a realtime hook ran in an island bundle that never installed realtime useQuery, useRecord, useMutation or useConnection in a browser island whose bundle never called installRealtime(), or on a page where the page runtime (@ultimat3/realtime/boot: the store, the socket, the transport) never loaded. A server render is not this: with no DOM the hooks answer their server-render state x build. It builds an island whose own import graph reaches @ultimat3/realtime from an entry that awaits the page runtime — the page boot, or the /islands/page-runtime.<id>.js chunk where no boot is rendered — and calls installRealtime({ signal: createSignal, cleanup: onCleanup }) first (packages/cli/src/island-realtime.ts). The one case it misses is a package that imports realtime on the island's behalf, or an island built by hand. That island's page loads import '@ultimat3/realtime/boot' before the island, and the island calls installRealtime({ signal: createSignal, cleanup: onCleanup }) (both from its own solid-js) in its mount, before its first render
X_REBASE_CONFLICT a local mutation could not be rebased server state moved incompatibly conflict: 'server-wins' on the mutator, or return a row from custom(merge)
X_RECORD_REJECTED a row reached the record store in a shape it cannot hold a row adopted into the page's RecordStore that is not an object, or has no record key. It is dropped and reported, never partially merged, because a keyless row would overwrite another record x entities show <entity> --json lists the primary key every row must carry. Return whole rows from the handler that built this one
X_REPLICATION_FAILED the replication connection was refused wal_level not logical, a role that may not create or extend the publication (the replicator ensures it at boot), a role without REPLICATION, a slot another replicator holds, wrong credentials the message names the object; the fix is the exact setting, CREATE PUBLICATION or pg_drop_replication_slot statement — and a REPLICATION grant only on a cluster dedicated to the app (why)
X_REPLICATION_PROTOCOL the WAL stream cannot be decoded a server or pgoutput version this build does not speak, or a proxy on the replication port x doctor --json — point the URL at postgres itself, on a server ≥ 14
X_REPLICATION_SLOT_INVALIDATED the replication slot was invalidated postgres invalidated the replicator's slot (wal_status = lost): it fell further behind than max_slot_wal_keep_size allows, so the WAL it needed is gone and it can never stream again SELECT pg_drop_replication_slot('<slot>'); — then restart the replicator: it recreates the slot and every live window resyncs
X_REPLICATION_SLOT_RECREATED the replication slot was recreated the replicator resumed from a position but its slot was gone (dropped, or a failover to a server that never had it), so a new slot was created and the changes committed in between were never streamed; every live window and channel is resynced from the database x doctor --json — find what drops the slot: a failover without slot sync (postgres 17 sync_replication_slots), or a manual pg_drop_replication_slot
X_REPLICATION_TLS the replication connection failed TLS the server certificate failed the verification the sslmode asks for (verify-ca: the chain; verify-full: the chain and the host name), sslrootcert names no readable file, or the TLS handshake itself failed openssl s_client -starttls postgres -connect "$PGHOST:$PGPORT" -showcerts </dev/null shows the chain and names the server presents; then pass its CA with ?sslrootcert=/path/to/ca.crt, connect with a name the certificate lists, or use ?sslmode=require to encrypt without verifying
X_REPLICATOR_SLOT_HELD another replicator already owns this database x dev --role replicator started while another process holds the database's replicator lock (a container that loses the lock stays up unready and takes over when it frees, so it never throws this) — nothing is wrong with this process, the database already has its one replicator x dev --role replicator # rerun after the replicator already on this DATABASE_URL stops — one database has one replicator
X_SOCKET_AUTH_UNAVAILABLE the sync node could not decide who a connecting socket is authenticate raised instead of deciding — a token service that timed out, a JWKS fetch that failed. The same rule the row gate follows: a failure is not a denial, so the client is told to come back rather than told it may not connect, and this one does page someone x doctor --json
X_SOCKET_LIMIT one principal holds too many sockets on this node the actor, or the anonymous client network, already holds the maximum number of open sync sockets on this node defineConfig({ realtime: { maxSocketsPerActor: 32 } }) — in app.config.ts — or close other tabs
X_SOCKET_ORIGIN_REFUSED the websocket upgrade came from another origin a browser page asked the sync node for a socket from an origin — scheme, host and port, compared exactly — that is not APP_URL's origin when one is declared; with none declared, not the origin the node was reached on. The session cookie would have ridden it. The same host name on another port, or over plain http, is another origin. The cause names the origin that asked and every origin the node admits; x dev also admits its own web role's origin and the origin it was reached on beside a declared one export APP_URL=https://www.example.com on the sync role — the refusal renders the origin that asked in its place; run it only when that is where the pages are served — or pass syncNode({ allowedOrigins })
X_SOCKET_UNAUTHENTICATED the sync upgrade carried no credential this app accepts the app's authenticate hook decided this upgrade belongs to nobody. A decision, not a fault — it never pages anyone, because the refusal is the whole point of the hook. Until this cycle there was no way to authenticate a WebSocket at all, so realtime was single-tenant only. Distinct from X_TOPIC_FORBIDDEN, which is a subscriber that already has a socket and asked for something it may not have; this one never gets a socket, so the client learns about it by tearing the connection down syncNode({ authenticate }) — send the credential it reads on the upgrade request, or return an anonymous Actor from it to admit this socket
X_SUBSCRIPTION_ID_TAKEN a subscribe frame reused a sid this socket already holds a hand-rolled client incrementing its own subscription ids, or a remount that reuses one. Subscriptions are keyed by (socket, sid), so a reused id would otherwise orphan the earlier subscription — its entry never reaching zero subscribers and never being freed crypto.randomUUID() — a fresh sid with each subscribe frame, what the bundled client uses
X_SUBSCRIPTION_LIMIT socket, actor, tenant or node hit its subscription cap a component subscribing in a loop, or one client minting distinct (query, input) pairs — a qid derives from client-chosen input, so the node holds a matcher and a row window per value. The scope in the message says which ceiling refused the actor scope: raise realtime.maxSubscriptionsPerActor in app.config.ts (default 1,000). Otherwise raise maxPerSocket / maxPerTenant / maxEntries on new LiveQueryRegistry({…}), or maxTopicsPerSocket / maxTopicsPerNode on new ChannelHub({…}) — none of those is an app.config.ts field
X_SYNC_UNCONFIGURED a live hook needed the page socket and no sync target was configured a live useQuery (or anything else that needs the page's one socket) ran, and neither installRealtime({ sync }) nor the document's <meta name="ultimate-sync"> named a target. x dev and the container render that meta on every document; a page served some other way does not serve the page through x dev or the container, which render <meta name="ultimate-sync"> (and SYNC_URL where the socket is not on the page origin). Or pass installRealtime({ signal: createSignal, cleanup: onCleanup, sync: { url, buildId } }) from @ultimat3/realtime
X_TOPIC_FORBIDDEN the actor may not subscribe to this topic a subscribe named a channel no channel() declares on this node, or the declaration's policy denied it (latched per socket and topic until the session changes) x policy list --json, then widen the policy on the channel() declaration this topic belongs to, or subscribe as an actor it allows
X_TRANSPORT_PROTOCOL the bus does not speak the protocol this build speaks nats-server older than 2.11, JetStream not enabled, or something that is not NATS on the port docker run -d -p 4222:4222 nats:2.11-alpine -js (or newer, with JetStream); reconnecting cannot fix it, so this never retries
X_TRANSPORT_UNAVAILABLE the fanout bus is unreachable the nats-server NATS_URL names is down or misconfigured. At boot only a sync node or a replicator raises it, after retrying the dial for 15 s — the cause names the server, the wait and the last attempt's own failure. A web, worker or scheduler process boots without the bus and raises it from a publish instead (publishChannelEvent, the cache-invalidation broadcast), at once, until its background dial lands; a publish made once the client's socket has closed is refused the same way rather than buffered by the client; the replicator retries such a refusal three times over 2 s before its run ends (Realtime → what each role needs from the bus) x doctor — then check NATS_URL; in app code, catch it around a publish and log — the event meant "re-read"

Clone this wiki locally