CastleError
A multiplayer socket closed before its first hello reports its WebSocket close
code in error.extensions.closeCode when available. Code 4404 means the
play proxy could not route the session (not_running); it does not prove the
runtime ended.
Multiplayer.join's session request asks the host again when it fails in transit
(CASTLE_HOST_ERROR, e.g. a 502 from Castle's API): after 1, 2, 4 and 8 s,
then the last error is thrown. A newer Multiplayer.join stops an older one's
tries. Any other code (FORBIDDEN, LOGIN_REQUIRED, ...) fails at once.
Every error the SDK throws is a CastleError. Check code to tell
the kinds apart.
Common codes:
-
LOGIN_REQUIRED— the player needs to be signed in. -
MISSING_DECK_ID— the deck hasn't been saved to Castle yet, so it has no id. -
CASTLE_STORAGE_SERIALIZE_FAILED— value isn't plain JSON (e.g. a class instance, a function, a non-finite number, or a cycle). -
INVALID_LEADERBOARD_VARIABLE,INVALID_LEADERBOARD_SCORE,INVALID_LEADERBOARD_TYPE— bad argument to aLeaderboardcall. -
UNSUPPORTED_TIMEZONE—Time.getServerDategot a zone other than'Castle'or'player'. -
CASTLE_HOST_UNAVAILABLE— the Castle host (the app or website running the deck) didn't handle the request — e.g. it timed out or wasn't reachable. Usually transient; retry or surface a gentle error. -
UNKNOWN_COMMAND("Unknown Castle command.") — the Castle app running the deck is a build older than the command. Each app build knows only the commands it shipped with, and only an app update adds one, so keep the deck working without it. The app's last version bump, iOS v1.149, came before every command below, so v1.149 and earlier builds lack all of them. Each date is the commit that added the command to the app's code, not when a build carrying it reached the stores; an app built from code before that commit answersUNKNOWN_COMMAND:Multiplayer.join— 2026-08-29Store(every method) — 2026-09-03Lifecycle.restoreState— 2026-09-08 (resolvesnullinstead of throwing)User.get— 2026-09-10Snapshot.offer— 2026-09-22Portal.info— 2026-09-22 (resolvesunavailableinstead of throwing)
Leaderboard.showresolvesunavailablerather than throwing on an app that lacks it. -
CAULDRON_STORAGE_STALE_GENERATION— the handle belongs to an older reset generation; reopen explicitly rather than replaying work into the new one.