Common Failures and Repairs

A runbook of failure classes AI agents hit when building in Gessa at engine version v1, with the canonical repair for each. The pattern is always the same: prefer a canonical surface, and treat backend acceptance and proof receipts as the truth. For canonical contracts, follow the links into the generated reference.

Each entry is Symptom | Cause | Canonical repair.

Authoring path failures

Empty script after create | Cause: ProjectScript create only accepts an empty IR shell; it does not author behavior. Canonical repair: apply behavior with Script Semantic Patch (project_apply_script_semantic_patch / project.script.patch.apply); the compiler lowers semantic operations into canonical Script IR. See Script Semantic Patch.

Hand-written Script IR rejected or drifts | Cause: full Script IR is generated output, not a hand-authoring surface; raw IR bypasses the semantic compiler and its guards. Canonical repair: never hand-write IR — express the change as semantic operations and apply the patch. See Script Node Catalog.

Raw Project Graph mutation rejected | Cause: project_apply_transaction (project.transaction.apply) is a low-level, workflow-exposure escape hatch and normal authoring is expected to route through cataloged verbs. Canonical repair: make the change through the matching project.* action (for example project.entity.create, project.entity.component.set, project.world.create). See Action Catalog.

Unknown component / action / tool name | Cause: the name was invented or remembered from another engine and does not exist at v1. Canonical repair: discover the live surface with engine_list_component_types, engine_get_component_schema, and MCP Tool Reference; use only names that appear there.

Component field rejected or ignored | Cause: a project.entity.component.set carried a field that is not in that component's contract, or a value of the wrong type; v1 has 24 built-in atomic components with a pinned field contract (ecs.component-field-contract.v1). Canonical repair: read the schema first with engine_get_component_schema (or the generated reference) and set only contracted fields. Do not invent fields, and remember gameplay concepts (health, damage, spawn pools) are script patterns, not component fields. See Component Types.

Raw shader / pass field rejected | Cause: the build contract forbids raw renderer fields such as shaderSource, fragmentShader, wgsl, glsl, and customPassSource. Canonical repair: reference a cataloged renderer/material capability id instead. See World Build Contract.

Proof and playability failures

AI claims playable, but Play shows missing camera / spawn / possession | Cause: renderability was treated as playability; required runtime proof was not produced. Canonical repair: require runtime proof — collision proxy, nav/query proxy, semantic anchor, and playability.accepted receipts — via simulation_run and the QA captures before claiming playable. See the World Build Contract acceptance policy.

Renderer / observer capture failed or degraded | Cause: qa_capture_* returned a degraded or failed frame. Canonical repair: handle degraded — report it as degraded and do not synthesize a passing receipt. Missing proof is not_run, not pass. Re-run capture or escalate; never fabricate.

Generation job never reached a terminal state | Cause: an asset was placed or a build was finalized while its generation_* job was still pending; accepted final proof only permits terminal_success, substituted, or degraded asset receipts. Canonical repair: poll generation_get_job until the job is terminal (or cancel it with generation_cancel_job) before treating the asset as final; report a degraded or substituted receipt honestly rather than waiting indefinitely or claiming success. See the World Build Contract.

Build accepted locally but not by backend | Cause: local UI state was trusted over backend authority. Canonical repair: the frontend is a non-authoritative projection — confirm acceptance and proof receipts from the backend before reporting success. The authoritative readiness registries live under docs/cycles/v1-engine-readiness-loop/ (FEATURE_LEDGER.json, PROOF_REGISTRY.json, GUARDRAIL_REGISTRY.json).

MCP and access failures

MCP tool unauthorized or out of scope | Cause: wrong or missing workspace / project handle. Canonical repair: discover scope with read-only tools (workspace_list, agent_get_project_context) and use the narrowest handle the task needs. See MCP tool use.

Downstream call leaks credentials | Cause: an MCP bearer token was forwarded to another tool or service. Canonical repair: never forward the MCP token downstream; it authenticates you to the Gessa MCP server only. See MCP Security.

Versioning failures

Contract claim does not match the engine | Cause: a page or assumption used a stale or second-attempt version spelling, or restated a contract instead of linking it. Canonical repair: pin to v1, cite the generated reference (Tier 2) for contract facts, and verify with the repo gates (npm run gen-docs:check, npm run check:version-coordinates). See Documentation Contract Architecture.