Error catalogue

Every failure irtio names has a stable E_* code. The 47 protocol codes also have stable numeric codes that will never be renumbered, so a client and a server built months apart still agree on what went wrong.

Where you see an error depends on which side raised it:

• Fatal server errors reject the joinRoom or joinRelay promise if the room was never joined, or close the connection and fire room.on('error', ...) with fatal: true.
• Non-fatal server errors fire room.on('error', ...) with fatal: false and leave you connected.
• RPC errors reject the promise room.call.<name>(...) returned.
• Room-side errors reject a promise inside your room file and never reach a client.
• Client-local errors never touch the wire at all.

Branching on a code

There is no error class to import. Connection errors arrive as a plain object on the error event, with exactly three fields:

interface RoomError {
  readonly code: string;    // 'E_ROOM_FULL', or 'E_INTERNAL' for a local failure
  readonly message: string;
  readonly fatal: boolean;  // fatal errors close the room
}

So the connection branch is a switch on e.code:

// main.ts
room.on('error', (e) => {
  switch (e.code) {
    case 'E_STARTING':
      showSpinner('waking the server');
      break;
    case 'E_ROOM_FULL':
      showMessage('this room is full');
      break;
    case 'E_SLOW_CONSUMER':
      // the client reconnects on its own; nothing to do but say so
      showMessage('reconnecting');
      break;
    default:
      if (e.fatal) showDisconnected(e.message);
  }
});

RPC failures are different, and the difference matters. room.call.<name>() rejects with a plain Error that carries no code property; read its message. When your handler refused the call with ctx.deny(reason), the message is deny: <reason>, which is the normal way a room says no. When irtio refused the call, or your handler threw, the message starts with the code and a colon:

try {
  await room.call.play({ card });
} catch (err) {
  const message = err instanceof Error ? err.message : String(err);
  if (message.startsWith('deny: ')) {
    showToast(message.slice('deny: '.length));   // your room's own reason: 'not your turn'
  } else if (message.startsWith('E_RPC_BAD_PARAMS')) {
    console.error('client and server schemas disagree', message);
  } else {
    console.error(message);
  }
}

A fatal error that arrives before the join completes rejects joinRoom with an Error whose message is the code, a colon, and the server’s message, so the same startsWith check works there.

Connection and identity

E_SCHEMA_MISMATCH is the error that catches “I changed a field and only redeployed one side”, which is exactly what it is for.

Tokens (JWT auth)

Raised only for joins that present a token. A join with no token can never hit these. See Authentication for the claims and setup these codes are checking.

Two of these are worth reading as configuration problems rather than attacks: E_TOKEN_BAD_ISSUER right after minting usually means the tenant has not been placed again yet, and E_AUTH on a token join means the project has no secret at all (irtio keys jwt-secret is the fix, and the error says so).

Rooms

A room that throws in tick three times in a row restarts from its last snapshot. A room that restarts too many times in a minute is closed with E_INTERNAL.

RPCs

To refuse an action, call ctx.deny(reason) in the handler. The caller’s promise rejects with the message deny: <reason>, and the room carries on:

// irtio/room.ts
rpc: {
  start(state, _params, ctx) {
    if (ctx.role !== 'host') ctx.deny('host only');
    state.match.phase = 'playing';
  },
}

The client catches an Error whose message is deny: host only. A handler that throws instead is treated as a bug: the caller gets E_INTERNAL: rpc start, and the thrown message goes only to irtio logs. See RPCs.

The client-side timeout message is rpc <name> timed out, with no code prefix. A call attempted while the socket is not open fails fast with its own message rather than waiting out the full timeout.

Writes and ownership

Note the difference from a correction: a validate handler that returns prev, or a clamped object, answers with a CORRECT carrying the server’s current values instead of either of these errors, and you see it on the client as room.on('correct', ...). See ownership.

Load and lifecycle

| E_STATE_CAP | 36 | no | A relay room with state is at its 512 KB state cap, and this write would have grown it. The write was refused; nothing was dropped, evicted or truncated, every other client is unaffected, and the room keeps serving. Read the room’s state size before you reach it: state that is the current situation fits the cap, and state that is a world or a history does not. A move log, a chat history or a growing canvas belongs in storage rather than in synced state; a world that streams by interest needs a room file | | E_RECORD_CAP | 37 | no | The collection named in the message is at its 1024-record cap, so the add was refused. Remove records you no longer need, or deploy a room file if the game genuinely holds more than a thousand of something | | E_WRITE_RATE | 38 | no | You sent more than 35 writes in a second on a relay room with state. The extra writes were not applied and the connection stayed open. One write per tick plus a buffer is the budget; batch your changes instead of writing per input event, and let room.flush() run once per frame rather than in a loop |

Faults

Player storage

These never reach a client. They reject the promise room.kv.get, set or delete returned, inside your room code, and the room keeps running. A limit is something to handle, not something to fall over on. They have no numeric code because nothing about them crosses the client socket.

Leaderboards

These never reach a client either. They reject the promise room.leaderboard.submit returned, inside your room code, and the room keeps running. There is no client-side submit at all, so there is no client-side failure to handle.

Quick-match and identity (HTTP)

These come back from the control plane over HTTPS, before any socket exists, so they arrive as a JSON body with a code and a message rather than on the error event.

Client-local

E_CONNECT_FAILED is not a protocol code. The connection failed or closed before the room was joined, so the server never got to name a reason. joinRoom and joinRelay reject with a message in one of these two shapes:

E_CONNECT_FAILED: cannot reach <url>: <reason> (the room was never joined)
E_CONNECT_FAILED: <url> closed the connection before the room was joined (code 1006)

Check the URL in the message. If it names your deployment, the tenant could not start, and irtio logs will say why. If it is a localhost URL, either irtio dev is not running, or you are in Node and expected production, in which case set IRT_URL.

A client that resolved its endpoint from the localhost default (step 3 of endpoint resolution) does not fail on 7070 alone: it probes 7171, 7272, 7373 and 7474 as well, because irtio dev binds those in turn when it cannot take 7070. The message names every port tried:

E_CONNECT_FAILED: cannot reach ws://localhost:7474: ... — no irtio dev server answered on any of
7070, 7171, 7272, 7373, 7474.

irtio dev prints the port it bound. Pass it as the url option, set window.IRT_URL = 'ws://localhost:<port>' before your bundle runs, or start the dev server with irtio dev --port 7070 to pin the port and fail loudly when it is unavailable.

A close before the join deliberately does not trigger reconnection. A join that never succeeded should fail rather than retry forever.

Deploy

See deploying and simulated players.

WebSocket close codes

A few refusals also get their own close code, so a client can act on onclose before it has parsed a frame. Everything else closes with 1008 (policy) or 1011 (internal error).

Related

• Client SDK
• Room file API