Troubleshooting

Start by identifying the failing stage and the last known-safe state. Avoid changing multiple authorities at once.

Decision path

Is the model blocked?
  └─ yes → fix or explicitly resolve the reported intent gap

Did generation fail?
  └─ yes → distinguish invalid/unsupported model from generator defect

Did the candidate fail before traffic?
  └─ yes → keep active release; inspect build, config, migration, readiness

Did the active release regress?
  └─ yes → assess rollback compatibility, then classify model/generator/ops cause

Is only a dependency or capacity failing?
  └─ yes → operate config, provider resilience, queue, cache, or infrastructure

Model is blocked

Read the finding identifier and target element. Check references, required creation data, permission scopes, mutation targets, query sources, and stale experience bindings. Do not remove meaningful constraints solely to pass the gate.

Generation fails

• Reproduce with the same revision, target, and generator version.
• Determine whether target preflight should have rejected the construct earlier.
• Preserve the smallest model fixture that demonstrates the failure.
• If the model is valid, fix the shared generator and add a conformance test.
• Generate into a fresh directory to exclude hidden prior output.

Preview returns 502 or never becomes ready

Inspect the candidate boot sequence:

1. database process and storage;
2. migration execution;
3. backend imports and startup;
4. frontend/static server;
5. reverse proxy;
6. readiness probe.

An ephemeral preview can be recreated. Do not apply preview cleanup rules to a published app.

Managed deployment is refused

Common classifications:

• schema_changed → current managed path cannot safely promote this schema-evolving revision;
• missing deploy configuration → managed infrastructure is not enabled;
• readiness timeout → candidate did not become safe for traffic;
• artifact/build failure → regenerate or repair the delivery machinery;
• release-chain mismatch → candidate does not descend from the destination’s recorded revision.

App runs but data appears missing

Verify the durable volume is mounted before redeploying or initializing anything. A machine started without its volume can create an empty database on ephemeral disk while the real data remains intact elsewhere.

Integration fails

Check in order:

• configuration is present and points to the intended environment;
• credentials and certificate validity;
• DNS and network reachability;
• rate limit or circuit state;
• provider contract versus modeled capability;
• callback signature and idempotency identity.

Performance degrades

Measure whether the bottleneck is saturation or strategy. Add capacity for saturation. Escalate unbounded queries, missing indexes, N+1 access, oversized payloads, or incompatible cache semantics to the model/generator layer.

Before retrying

Confirm the failed operation is idempotent and reconcile observed state. A timed-out migration or provider request may have completed even when the caller did not receive confirmation.

See Health and validation and Authority boundaries.