Troubleshooting

Start with the Worker health check:

Terminal

curl -i "$TURBO_API/management/health"

Common issues

Symptom	Likely cause	Fix
Turbo auth fails	missing/wrong bearer token	set matching Worker secret and client env
`403` on upload	token lacks write scope	check scoped token `scopes`
`403` on team	token cannot access team	check `TURBO_TEAM` and token `teams`
`403` on PR write	`read-only-pr` policy	use main branch or change policy
`413` in KV mode	artifact above KV limit	use R2
no cache hits	different task hash	inspect Turbo inputs, env, git dirty state
internal route `503`	admin token or optional DB missing	configure `INTERNAL_ADMIN_TOKEN`, `TOKEN_DB`, or `ARTIFACT_INDEX`
lifecycle fails	Cloudflare API settings	check account id, API token, bucket name, jurisdiction

Verify live Worker auth

Unauthenticated status should be rejected:

Terminal

TURBO_TOKEN=bad-token turbo run build --cache=local:,remote:r

Authenticated status should work:

Terminal

turbo run build --cache=local:,remote:r

Verify R2 binding

Run a Wrangler dry-run build:

Terminal

pnpm build

The output should show:

env.ARTIFACTS (...) R2 Bucket

Verify Turbo cache behavior

Run with full logs:

Terminal

TURBO_API=... TURBO_TOKEN=... TURBO_TEAM=... \
turbo run build --cache=local:,remote:w --output-logs=full
rm -rf .turbo
TURBO_API=... TURBO_TOKEN=... TURBO_TEAM=... \
turbo run build --cache=local:,remote:r --output-logs=full

Look for Turbo remote cache lines and a cache hit on the second run.

If repeated runs miss, check:

Check	Why
`TURBO_TEAM` stable	team is part of remote cache namespace
task outputs configured	Turbo cannot restore missing outputs
env vars in task hash	changed env means changed hash
dirty files	workspace state can affect hashes
branch policy	branch namespace may isolate reads

Local integration proof

The repo includes a real Turbo fixture test:

Terminal

pnpm test:integration

It runs a local Worker handler, uploads artifacts on the first run, and restores cache hits on the second run.