Troubleshooting

#Troubleshooting

When something goes wrong, start here. This section covers common problems grouped by category, each with a clear symptom, cause, and fix.

#How to use this section

Each troubleshooting page follows a consistent format:

1. Problem — What you're experiencing (matched to what you'd search for)
2. Cause — Why it happens
3. Fix — Step-by-step instructions to resolve it
4. Prevention — How to avoid it in the future

#Common issues by category

#Authentication errors

• 401 unauthorized — Missing or invalid Bearer token
• 403 forbidden — Valid token but insufficient permissions
• 403 signup_forbidden — Registration blocked because the caller's role can't create users
• 429 rate_limited — Too many authentication attempts (5 per minute per IP)

#Query and data access errors

• 404 collection_not_found — Collection name doesn't match any registered schema
• 404 record_not_found — Record ID doesn't exist or is hidden by row-level security
• 422 validation_error — Request body failed field validation
• 400 invalid_name — Collection or field name contains invalid characters

#Deployment issues

• Worker deployment fails — Check wrangler.toml bindings match your Cloudflare account
• D1 migration errors — Run migrations in order with wrangler d1 migrations apply
• R2 upload failures — Verify the FILE_STORAGE binding points to an existing R2 bucket

#Scheduled tasks aren't running

• No scheduled backups appear, though the schedule is on — the hourly maintenance tick has stalled
• A scheduled automation flow silently stopped firing — its Durable Object alarm was never re-armed
• Runs stuck in pending/running forever — nothing is reaping them
• Handler does not export a scheduled() function in the Worker logs — the cron trigger has no reachable handler

#Debugging tips

• Check the X-Request-ID header on error responses — use it to search logs
• Enable verbose logging in the dashboard under Settings → System Health
• For automation flow failures, check Automation → Runs for step-by-step execution logs
• The error response always includes a machine-readable error code and a human-readable message

#Guides in this section

• Authentication errors — sign-up 403s, rate limiting, API key permissions, and stale sessions
• Query and data access errors — invisible collections, missing records, and CORS problems
• Deployment issues — local dev secrets, database bindings, script execution, and rollback
• Scheduled tasks aren't running — a stalled hourly maintenance tick, missing cron triggers, and tasks that fail every hour