Reference

Errors and troubleshooting

Common symptoms, causes and how to fix them.

Players can't move during the match

Symptom: the match starts, but the discs stay still at spawn (pale and nameless).

Common cause: the room is locked (lockTeams()) and the match start was sent with gs.tl = false.

Fix: use version 0.1.4 or later, which sends gs.tl according to the real lock state. If you build TRIGGER_START by hand, fill gs.tl with the value of room.state.teamsLocked.

A player who joins mid-match is stuck in the lobby

Cause: the host sent INFORM_IN_LOBBY and then INFORM_IN_GAME (or the other way round). The client only accepts one initial-data packet.

Fix: since 0.1.2 the library sends only INFORM_IN_GAME when there is an active match started with startGame({ is }). If you start matches some other way, pass the is so the room knows a match is in progress.

The match starts, but players don't appear on the field

Cause: the IS blob is empty or doesn't match the map/number of players.

Fix: capture a blob for each combination (see Matches and IS blob) and use an explicit bal.

rate_limit_tl, rate_limit_cot and others

Cause: too many commands in a short time. The server refuses and warns with a status-message.

Fix: space out the calls. A repeated lockTeams() already sends only once and retries by itself if refused.

Cause: in versions before 0.1.3, room ids with fewer than 6 digits came without leading zeros (for example 6813vnxpi instead of 006813vnxpi).

Fix: update the library; room.shareLink now comes complete.

RoomCreationTimeoutError or RoomJoinTimeoutError

The server didn't answer in time (default: 10 s). Check the network and the credentials and try again. Increase timeoutMs on slow networks.

room-dead with status-room_full

When the bot wasn't in the room yet, it means the room is full (terminal). If it already was, the notice only indicates that another player was refused.

TypeScript errors coming from node_modules/bonktools

If you compile with skipLibCheck: false, the package's index.d.ts may show errors about socket.io-client and eventemitter3. Keep skipLibCheck: true (the tsc --init default); with it, the types work fully.

Anti-AFK flags everyone

Movement comes from input frames over WebRTC. If the players' tabs are in the background, or WebRTC didn't connect, no frame arrives. See the anti-AFK limitations and check that peer-input is being emitted.

Players can't move after someone leaves and others join

Cause: a blob captured with the ids of another session (the IS blob holds one disc per player id).

Fix: use version 0.2.0 or later and build the state with ScoreTracker.buildInitialState (or remapInitialStatePlayers for a captured solo blob).

The game sometimes doesn't render (dark screen) on start

Cause: the is was encoded with LZString.compressToBase64. The client decodes with decompressFromEncodedURIComponent and truncates the state when / or = show up (RangeError: Illegal offset in PSON).

Fix: update to 0.2.0 (encodeInitialState uses the right alphabet) and don't send blobs encoded by another tool with plain base64.

The loser goes to spec instead of playing again

Common cause: they were flagged AFK for going 12 s without pressing a key at the end of the match. Fix: in 0.2.0 a held key counts as activity and, in matches ended by score, final inactivity is ignored. In tests, use BONK_DEBUG=1 to turn automatic AFK off.

The room plays 1v1 even with many players

Cause: without BONK_MAXTEAMSIZE in .env the old app assumed 1. Fix: set BONK_MAXTEAMSIZE=2 (the default is now 2).

Frequently asked questions

Do I need a bonk.io account? To host 24/7 rooms, yes: use a registered account.

What systems does it run on? It is Node.js (20.18.1 or later) with no browser and no native game dependencies. Development and testing were done on Windows.

Can I run several rooms? Yes, with BonkSession. A single account can keep several rooms, respecting the throttle.

Is it official? No. It is an independent project, with no affiliation with bonk.io.

Where do I report a problem? Open an issue in the library repository.