Find your symptom, get the fix. Errors come with machine-readable codes — locally
raised codes come from the SDK, kebab-case codes like room-not-found come from the
server. Turn on SpawnWeaver.set_debug_enabled(true) to see them all in the output.
Install & plugin issues
| Symptom | Cause | Fix |
|---|---|---|
SpawnWeaver is "not declared in the current scope" |
Plugin not enabled | Project → Project Settings → Plugins → enable "SpawnWeaver", restart the editor |
| "PlayerSpawner: the SpawnWeaver plugin is not enabled" / same for SpawnSync | Nodes used without the autoload registered | Enable the plugin; the autoload registers at /root/SpawnWeaver |
| No SpawnWeaver dock in the editor | Plugin disabled, or addon extracted to the wrong path | The addon must live at addons/spawnweaver/; re-run the installer from the folder containing project.godot |
| Installer script fails to download | No network, or a proxy blocking the download | Check https://spawnweaver.dev/health opens in a browser; use the manual zip install as fallback |
| Errors after upgrading the addon | Editor caching old scripts | Close Godot, delete .godot/ cache folder if needed, reopen |
Connect failures
start() fails, or the dock's Test connection reports an error.
| Symptom / code | Cause | Fix |
|---|---|---|
not-configured — "No project key" |
No key in the dock, spawnweaver.cfg, or configure() |
Paste your pk_… key in the dock and Save |
connect-failed — "is the server reachable and the project key valid?" |
Wrong URL, server down, or handshake rejected | Check the Server URL; for local dev confirm http://localhost:5159/health; verify the key |
| Handshake rejected with 401 | Missing/unknown/inactive project key, or an invalid/expired player token | Copy the key again from the dashboard; a deactivated project or rotated public key also 401s |
| Handshake rejected with 403 | Web build served from an origin the service rejects | Native builds are unaffected; for web builds, contact us to allow your game's origin |
| Handshake rejected with 429 | The project's connection cap is reached | Retry with backoff; contact us before a launch spike to raise the cap |
| Works locally, fails in a release build | Using ws:// against a TLS server (or vice versa) |
Hosted/production is wss://…/connect; plain ws:// only for local unproxied dev |
| Connects, then drops after ~45s repeatedly | A proxy on the player's network kills idle WebSocket traffic | Common on corporate/school networks — the SDK's auto-reconnect recovers, but sustained play needs a network that allows wss:// |
In-game errors
These come back on the awaited SWResult (or the error signal for send_event).
| Code | When | Fix |
|---|---|---|
not-connected |
Any request before start() succeeded (SDK-local) |
await SpawnWeaver.start() once at boot; check SpawnWeaver.is_online() |
not-in-room |
Room-scoped call (events, state, leave) without a room | Create/join a room first |
already-in-room |
create_room/join_room/find_match while in a room |
await SpawnWeaver.leave_room() first — one room per connection |
room-not-found |
Bad code, or the room expired (empty-room TTL, server restart) | Re-check the code; recreate the room |
room-full |
max_players reached — in-grace members count |
Wait, or raise max_players via the host's update_room() |
not-host |
update_room() or set_room_state() from a non-host |
Check SpawnWeaver.is_host; react to host_changed |
state-forbidden |
Writing an entity another player owns | Only the creator writes an entity; route via its owner or an event |
state-limit-exceeded / state-too-large |
Too many entities / entity or room state too big | See Limits; delete finished entities, slim the state |
rate-limited |
Message or state budget exceeded (retryable) | Back off and retry; cap send rates (Limits) |
payload-too-large |
A message over 16 KB | Shrink the payload; big data belongs in storage |
entity-not-found |
Patch/delete of an entity that doesn't exist | Create with set_entity() first; it may have been GC'd when its owner left |
storage-invalid-key / storage-value-too-large / storage-quota-exceeded |
Storage rules violated | Key ≤128 chars, value ≤64 KB, ≤100 keys — delete old keys |
invalid-payload |
A malformed field (e.g. matchmaking size outside 2–64, \| in mode/region) |
Fix the offending field; the message says which |
timeout (SDK-local, retryable) |
No reply within 10s (120s for find_match) |
Usually a dying connection — the SDK reconnects; retry the call |
disconnected (SDK-local, retryable) |
Connection dropped mid-request | Retry after connected fires; queued events flush automatically |
cancelled (SDK-local) |
You called cancel_matchmaking() |
Expected — not an error to surface to players |
match-timeout (retryable) |
No match within the server window | Offer "search again" (Matchmaking) |
malformed-message / unknown-message-type |
Hand-rolled protocol messages, or SDK/server version mismatch | Upgrade the SDK and server to matching versions |
Editor dock issues
| Symptom | Cause | Fix |
|---|---|---|
| Test connection fails but the key is right | Server field points somewhere stale (e.g. an old local port) | Clear the Server field for hosted, or set ws://127.0.0.1:5159/connect for local |
| "Live: —" never updates | Stats need a saved, valid key; the poll hits /connect/stats?projectKey=… |
Save the key first; verify the server is reachable from the editor |
Dock shows old values after quickstart.ps1 |
Config was written while the editor had the file cached | The script writes res://spawnweaver.cfg; reopen the project or reload the dock |
| Starter scene button does nothing visible | Scene generated to res://spawnweaver/ |
Look for res://spawnweaver/StarterGame.tscn in the FileSystem panel |
Reconnect loops
The reconnecting(attempt, delay) signal fires repeatedly and the game never settles.
| Cause | How to tell | Fix |
|---|---|---|
| Service unreachable (outage or local network) | Attempts climb forever; connect-failed details in debug output |
The SDK backs off to 30s between attempts and recovers alone once the connection is back |
| Project key deactivated or rotated mid-session | Reconnects are rejected (401) over and over | Ship the new key; call stop() and surface a "update required" message |
| A proxy/VPN on the player's network kills WebSocket traffic | Connects fail or drop only on that network | Players on corporate/school networks may need to allow wss:// to spawnweaver.dev |
While reconnecting, awaited calls fail fast with disconnected and send_event calls
queue automatically — design the UI to show a "reconnecting…" state rather than
erroring. When the session resumes, connected fires and, if your room seat survived
the grace window, room_joined fires again with the fresh state.
Still stuck?
SpawnWeaver.set_debug_enabled(true)and read the message log.- Copy
SpawnWeaver.create_debug_report_string()and paste it into the dashboard's Debug Bundle viewer. - Find the session in the session inspector — the timeline shows every rejection with its code.
- See Debugging for the full toolbox.