# Cake20 Error Classification

Classify a failure before changing source. Preserve the original error text and the
operation that produced it.

## Source policy failure

Symptoms: rejected folder, cross-runtime import, unsupported executable code,
forbidden package, invalid `package.json`, or invalid DB source.

Recovery:

1. Read `core.md` and the current error path.
2. Move code into an allowed source root.
3. Replace cross-boundary imports with shared utilities or server APIs.
4. Remove generated, platform, or unsupported dependency declarations.
5. Re-run validation before building.

## Type or API failure

Symptoms: unknown Runtime global, wrong handler signature, missing component, or stale
example.

Recovery:

1. Inspect installed Runtime declarations and generated editor types.
2. Prefer the installed version over public examples.
3. Run `cake prepare` or `cake doctor --fix` if managed types are missing.
4. Change only the incompatible call site.

## Build failure

Symptoms: UI compilation, server preparation, dependency installation, schema
generation, or release creation fails.

Recovery:

1. Fix the first actionable error, not downstream noise.
2. Confirm source policy and `package.json` first.
3. Confirm external dependencies are declared and allowed.
4. Confirm DB models are syntactically valid and relations resolve.
5. Build again; do not delete persistent `files` or database data.

## Runtime start failure

Symptoms: no current release, port conflict, unavailable database, missing Secret, or
process exits after a successful build.

Recovery:

1. Confirm a current release exists; build if none exists.
2. Use another port when the selected port is occupied.
3. Confirm the selected data mode and database availability.
4. Configure required integrations through Secrets, not source constants.
5. Inspect current release logs.

## Database failure

Symptoms: model validation, migration, relation, generated client, connection, or seed
failure.

Recovery:

1. Separate schema errors from connection and data errors.
2. Validate `.nullable()`, relation targets, index declarations, and field types.
3. Keep seed data deterministic and safe to re-evaluate.
4. Back up before import or destructive migration work.
5. Never replace production data without explicit authorization.

## MCP access failure

Symptoms: unauthorized, forbidden, expired URL, missing scope, or unavailable website.

Recovery:

1. Do not retry mutations blindly.
2. Request a fresh website-scoped MCP URL when the access token expired.
3. Confirm the requested operation is within the granted scope.
4. Re-read website state after reconnecting before continuing edits.

## Synchronization conflict

Symptoms: local and server source both changed, project ID mismatch, or replacement
would overwrite a non-empty directory.

Recovery:

1. Run status and diff inspection.
2. Preserve both sides before choosing a source of truth.
3. Use force or replacement only after explicit review and authorization.

## Compatibility failure

Symptoms: a release built with another Runtime line cannot start or a declaration
changed across versions.

Recovery:

1. Compare release Runtime metadata with the installed Runtime.
2. Patch upgrades should remain artifact-compatible; report a regression if they do
   not.
3. For a minor or major Runtime change, rebuild is recommended.
4. Do not rebuild all templates merely because a patch version changed.