Troubleshooting

The admin site cannot talk to the API

Set one of the following before building or deploying the admin app:

• CF_WORKERS_SUBDOMAIN
• VITE_API_BASE_URL

If neither is present, the admin site can render but API calls will fail.

Model calls fail through AI Gateway

If the selected model provider is workers-ai-gateway, the runtime expects AI_GATEWAY_ID.

Example:

export AI_GATEWAY_ID="your-gateway-id"

Telegram webhook returns 401

Check that TELEGRAM_WEBHOOK_SECRET matches the secret passed when the webhook was registered.

Telegram messages do nothing

Check these first:

1. TELEGRAM_BOT_TOKEN is configured on both the API Worker and runtime Worker.
2. The runtime Worker is deployed after the latest Telegram-related changes.
3. The chat is actually bound to the workspace.
4. The queue consumers are healthy.

Useful commands:

pnpm telegram:smoke:staging
pnpm cf:deploy:runtime:staging

I need the Telegram chat id

Send a message from the target chat to the webhook before the binding exists. The API returns a fallback response that logs the chat id and helps with seeding.

A run is stuck or failed

Use the admin dashboard run monitor or fetch the trace directly:

GET /api/workspaces/:workspaceId/runs/:runId/trace

If a queue job has moved to dead-letter, inspect:

GET /api/workspaces/:workspaceId/queue/dead-letter

Migrations or deploys are failing

Re-run the resource and migration commands in order:

pnpm cf:provision
pnpm cf:migrate
pnpm cf:deploy

For environment-specific issues, prefer the matching :staging or :production commands.