Exception Handling in Rooms

🆕

This feature is available since @colyseus/core version 0.15.55.

By default, if an uncaught exception occurs inside a room, the server is shut down ungracefully. This shutdown disconnects all clients, and the server will restart or stop running (depending on how it’s configured).

You can now handle uncaught exceptions by implementing the onUncaughtException() method in your room class. With this method, all user-facing callbacks will be wrapped in try/catch blocks, and any exceptions will be forwarded to onUncaughtException().

MyRoom.ts

import { Room } from "colyseus";
 
class MyRoom extends Room {
    // ...
    onUncaughtException (err: Error, methodName: string) {
        console.error("An error ocurred in", methodName, ":", err);
        err.cause // original unhandled error
        err.message // original error message
    }
    // ...
}

Methods that can throw exceptions are:

onCreate()
onAuth()
onJoin()
onDrop()
onReconnect()
onLeave()
onDispose()
onMessage()
setTimestep() / setFixedTimestep() (and the deprecated setSimulationInterval() alias)
clock.setTimeout()
clock.setInterval()

⚠️

Exceptions in onAuth and onJoin

Any uncaught exception thrown during onAuth or onJoin will still result in a failure to join the room, even if caught by onUncaughtException. If needed, you may have your own try/catch block in onAuth or onJoin to ensure clients can join even in case of an exception.

Exception Types

The following exceptions are thrown by the server and can be caught by onUncaughtException:

Each exception type has context information that can be accessed through its properties.

OnCreateException

When the exception is thrown inside the onCreate method.

Properties:

options - the options passed to the room’s onCreate method.

MyRoom.ts

import { OnCreateException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnCreateException) {
            err.options; // the options passed to the room's `onCreate` method.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
// ...

OnAuthException

When the exception is thrown inside the onAuth method.

Properties:

client - the client that is trying to authenticate.
options - the options passed to the room’s onAuth method.

MyRoom.ts

import { OnAuthException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnAuthException) {
            err.client; // the client that is trying to authenticate.
            err.options; // the options passed to the room's `onAuth` method.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }

OnJoinException

When the exception is thrown inside the onJoin method.

Properties:

client - the client that is trying to join the room.
options - the options passed to the room’s onJoin method.

MyRoom.ts

import { OnJoinException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnJoinException) {
            err.client; // the client that is trying to join the room.
            err.options; // the options passed to the room's `onJoin` method.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }

OnLeaveException

When the exception is thrown inside the onLeave method.

Properties:

client - the client that is leaving the room.
consented - the close code associated with the client leaving the room.

MyRoom.ts

import { OnLeaveException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnLeaveException) {
            err.client; // the client that is leaving the room.
            err.consented; // the close code associated with the client leaving the room.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }

OnDropException / OnReconnectException

When the exception is thrown inside onDrop (properties: client, code) or onReconnect (property: client).

⚠️

In 0.18.1 these two classes are raised internally but not yet exported from the colyseus package, so an instanceof check isn’t possible. Inspect the methodName argument ("onDrop" / "onReconnect") instead.

OnMessageException

When the exception is thrown inside the onMessage method.

Properties:

client - the client that sent the message.
payload - the message payload sent by the client.
type - the message type sent by the client.

MyRoom.ts

import { OnMessageException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnMessageException) {
            err.client; // the client that sent the message.
            err.payload; // the message payload sent by the client.
            err.type; // the message type sent by the client.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }

OnDisposeException

When the exception is thrown inside the onDispose method.

MyRoom.ts

import { OnDisposeException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnDisposeException) {
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }

TimestepException

When the exception is thrown inside the setTimestep or setFixedTimestep callback (methodName is "setTimestep" / "setFixedTimestep"). SimulationIntervalException remains as a deprecated alias.

MyRoom.ts

import { TimestepException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof TimestepException) {
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }

TimedEventException

When the exception is thrown inside the clock.setTimeout or clock.setInterval methods.

Properties:

args - optional arguments passed to the timeout or interval.

MyRoom.ts

import { TimedEventException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof TimedEventException) {
            err.args; // optional arguments passed to the timeout or interval.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }

Reconnection Handling Room Plugins