Error codes
Every developer-facing CIG2 error ends in a code like [CIG2-E101]. Look one up with cig context errors E101. The code is part of the message, so errors.Is against the sentinel still works.
CIG2-E101 — journal replay diverged
A replayed journal produced a different state digest from the one it recorded, at the step named in the error.
Cause: one of two things.
- The game’s rules or code changed since the journal was recorded. The error names the recorded game version.
- The game is nondeterministic:
time.Now, ranging a map while drawing randomness, or state in package variables.
Fix:
- Nondeterminism. Read the clock with
s.Now(). Sort map keys, or useCollector.All, before callings.Rand,Ask,NewCardorSchedulein a loop. Keep all state inSetStateorSetPlayerState.cig checkfinds the first two. - A rules change. Finish in-flight games before deploying new rules, or accept that their tables won’t restore.
CIG2-E102 — journal cannot be replayed
Cause: one of three things.
- The session used
WithRand, a random source the journal can’t capture. - A
Session.Dochanged state outside any step, so the journal is tainted. - The journal is malformed, or for another game or seat list.
Fix:
WithRand. UseWithSeedinstead (or nothing: the default source is recorded).- A tainted journal. Change state through actions, not
Do. - A malformed journal. Check the journal belongs to this game and seats.
CIG2-E103 — Session.Do changed game state
A Session.Do on a journaled session changed game state outside any step. The journal can’t record that, so by default the session fails.
Fix: use Do only to read. Make changes through actions (Apply), or from the inspector, whose writes are journaled. A test that must stage a precondition can, because cig2test tables taint the journal instead of failing. Their replay check is then skipped.
CIG2-E201 — a rejected action changed state
HandleAction returned an error after changing game state. A rejection is broadcast to nobody, so the change is invisible to every other seat.
Fix: validate everything, then mutate. Return errors only before the first change.
CIG2-E202 — settle did not converge
The settle loop (SetSettle steps plus phase auto-advance) ran SettlePassLimit passes without reaching a fixpoint.
Fix: a settle step must return true only when it changed something, and must eventually stop changing things. A ring of phases whose NeedsInput is always false cycles forever. Give at least one phase a predicate that waits.
CIG2-E203 — SettleNow called during a settle
Fix: don’t call SettleNow from a settle step or phase hook. It is already settling.
CIG2-E204 — called off the actor goroutine
An actor-only method was called from another goroutine.
Fix: call it from Setup, HandleAction, CheckEnd, a settle step or a hook. From outside, wrap the call in Session.Do. Build with -tags cig2debug to panic at the exact call site.
CIG2-E205 — the actor goroutine exited
Something on the actor called runtime.Goexit. In tests that is almost always t.Fatal or t.FailNow inside a Session.Do closure or a game callback.
Fix: read values out of Do into locals, then assert on the test goroutine. cig check (fatalinactor) finds these.
CIG2-E206 — session failed
A panic in game code changed state, or a journal append failed, so the table stopped. Err wraps the PanicError, whose stack the inspector shows.
Fix: read the panic in the log or the inspector. A host answers 500 for the table until it is reset.
CIG2-E207 — reserved action name
Action names starting with cig2. belong to the framework. cig2.answer is the only one a client may send.
Fix: rename the game’s action.
CIG2-E301 — bad config
DecodeConfig rejected a table’s config: an unknown field, the wrong type, or a Validate failure. A host answers 400 and starts nothing.
Fix: match the game’s config type. GET /describe gives its schema.
CIG2-E302 — state has the wrong type
StateOf found a SetState value of a different type.
Fix: call SetState with the type you read back, in Setup.
CIG2-E303 — no such zone
FindZoneAs was given a zone ID that doesn’t exist.
Fix: check the ID, and that the zone was created with a Session.New* factory.
CIG2-E304 — zone has the wrong type
Fix: ask FindZoneAs for the type the zone was created as (*cig2.Deck, *cig2.Hand, …).
CIG2-E401 — no app password
The host’s password gate fails closed.
Fix: set Auth.Password or PasswordEnv, or, for local development only, AllowOpen.
CIG2-E402 — the inspector needs credentials
The inspector shows every hidden card, so it never runs open.
Fix: give it its own password (-inspector-password-env) or an Authorize func, such as Identity.InspectorAuthorize for admins.
CIG2-E501 — a hidden card’s UUID was sent to a seat
cig2test.Explore found the UUID of a card the seat may not identify somewhere in its frames. The card is in a Hidden, FaceDown or another seat’s Concealed zone. The visibility filter never emits such UUIDs, so the game wrote it: in GameState, a decision prompt or choices, a hint’s data or label, or an error message.
Fix: never put a hidden card’s UUID in game-authored data. To let a seat choose among cards it peeked, move them into a zone it owns first.
CIG2-E502 — a hidden card’s identity was sent to a seat
The payload of a card hidden from the seat appeared in its game state, prompts or hints.
Fix: derive per-seat game state from what that seat may see. GameState(s, viewer) exists so the game can filter.
CIG2-E503 — a hinted action was rejected
LegalActions offered an action that HandleAction then rejected.
Fix: derive hints and validation from the same predicate, so they can’t disagree.
CIG2-E504 — deadlock
The game isn’t over, no seat has a legal hint or a decision to answer, and no timer is pending.
Fix: make CheckEnd notice the end, offer a hint, or arm a timer.
CIG2-E505 — the game never ended
A random game ran past MaxSteps (default 5000).
Fix: check that the game can end from every state. Raise MaxSteps for games that are genuinely long; random play takes far more actions than people do. For a game random play need not finish (a solitaire that can cycle its stock, a game where passing is always legal), add cig2test.MayNotEnd(), with a MaxSteps that fits your time budget. This failure has no reproducer, since the whole game is the reproduction; rerun with the reported seed (cig2test.Seed).
CIG2-E506 — the session failed during Explore
Fix: see CIG2-E206. The reproducer replays the failing game exactly.
CIG2-E507 — the test’s journal did not replay
Every cig2test table replays its own journal when the test ends. This one diverged, so the game is not deterministic, and a host could not restore it after a restart.
Fix: see CIG2-E101. Table.SkipReplayCheck opts out, for a test that is deliberately nondeterministic.