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 use Collector.All, before calling s.Rand, Ask, NewCard or Schedule in a loop. Keep all state in SetState or SetPlayerState. cig check finds 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.Do changed state outside any step, so the journal is tainted.
  • The journal is malformed, or for another game or seat list.

Fix:

  • WithRand. Use WithSeed instead (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.