Troubleshooting

Start with the smallest deterministic check that isolates the failing layer.

make dev says the API never became ready

Run:

make backend-workspace-smoke
make backend-smoke

If the clean temporary-data smoke succeeds but the workspace-data smoke fails, inspect persistent-state diagnostics before deleting anything. Optional integrations should fail soft where their contract allows it; do not erase the data root as a first response.

The Agent plans work but then reports an internal protocol failure

Check the task trace. A tool can be denied before execution when its call ID, kind, availability, or arguments violate the model/tool protocol.

For direct-path object stores, an explicitly supplied authorized object path can be inspected even when object listing is empty. Provider-backed relations still must be explicitly discovered.

The model responds with prose but does not execute tools

Production Agent execution requires native tool/function calling. Confirm that the configured transport and model support structured tool calls, then use Settings → Models → Test.

A feature is missing from the UI

The UI is capability-negotiated. Inspect GET /api/v1/bootstrap and confirm the Server advertises the relevant stable capability. Known missing capabilities disable the UI rather than relying on downstream 404s.

Cloudflare deploy says site-dist does not exist

The build must run before Wrangler deploys:

Build command:  bash scripts/build-cloudflare-website.sh
Deploy command: npx wrangler deploy

wrangler.toml serves ./site-dist. For Cloudflare Workers Builds / Git integration, configure the Build command under the Worker's Settings → Build. Workers Builds currently does not honor Wrangler Custom Builds, so adding a [build] command to wrangler.toml does not replace that setting. Keep the build root at the repository root so the script path and site-dist output resolve consistently.

The website build reports a dead link

Run the local build and fix the source Markdown link. The renderer validates generated internal references and intentionally fails instead of publishing a broken navigation path.

A report opens but data is unavailable

Large query payloads have a bounded TTL that is independent from report/artifact metadata. A report can retain its ReportSpec and provenance after an underlying payload expires. Re-run the analytical evidence when fresh data is required.