---
title: "Common Failures and Repairs"
description: "A runbook of failure classes AI agents hit when building in Gessa at engine v1, each as Symptom | Cause | Canonical repair."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/ai/common-failures-and-repairs/
---

# 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](../../spec/generated/script-semantic-patch.md).

**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](../../spec/generated/script-node-catalog.md).

**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](../../spec/generated/action-catalog.md).

**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](../../creator/mcp/tool-reference.md); 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 ships a fixed set of built-in atomic components with a pinned field contract
(`ecs.component-field-contract.v1`), enumerated in the generated component reference. **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](../../spec/generated/component-types.md).

**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](../../spec/generated/world-build-contract.md).

## 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](../../spec/generated/world-build-contract.md) 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](../../spec/generated/world-build-contract.md).

**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`, `project_list_games`, and the targeted `project_get_*` reads) and
use the narrowest handle the task needs. See [MCP tool use](./mcp-tool-use.md).

**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](../../creator/mcp/security.md).

## 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](../../docs-system/DOCUMENTATION_CONTRACT_ARCHITECTURE.md).