Use when wrangler deploys silently fail or produce wrong artifacts, secrets upload as empty strings, custom domain DNS is not resolving, route assignment broke after rename, observability/tail logs are needed, D1/KV/R2 bindings are missing, OAuth scope errors block a command, cookies on a redirect are not attaching, or the worker exceeds CPU time. Triggers: "Tenant or user not found", "Authentication error" on wrangler d1 push, secret length is 0 after upload, route returns origin not worker, "compatibility_date too old", 1101 errors, custom_domain assignment lost on script rename. NOT for AWS Lambda / Vercel Edge / Deno Deploy (different runtimes), Cloudflare Zero Trust, or R2-specific tuning.
Instrucciones de origen · Vista previa de solo lectura
license
Apache-2.0
allowed-tools
Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
name
cloudflare-workers-debugging
description
Use when wrangler deploys silently fail or produce wrong artifacts, secrets upload as empty strings, custom domain DNS is not resolving, route assignment broke after rename, observability/tail logs are needed, D1/KV/R2 bindings are missing, OAuth scope errors block a command, cookies on a redirect are not attaching, or the worker exceeds CPU time. Triggers: "Tenant or user not found", "Authentication error" on wrangler d1 push, secret length is 0 after upload, route returns origin not worker, "compatibility_date too old", 1101 errors, custom_domain assignment lost on script rename. NOT for AWS Lambda / Vercel Edge / Deno Deploy (different runtimes), Cloudflare Zero Trust, or R2-specific tuning.
metadata
{"category":"DevOps & Infrastructure","tags":["cloudflare","workers","wrangler","pages","d1","deployment","debugging"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"cdn-cache-control-headers","reason":"A Worker that \"isn't updating\" is often a cache-header problem at the edge, not a deploy problem — rule that out with this pairing."},{"skill":"websocket-realtime-expert","reason":"Durable Object / WebSocket surfaces on Workers add realtime failure modes beyond the deploy/auth catalog here."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}
Cloudflare Workers Debugging
Wrangler papers over a lot, but when it leaks, it leaks badly. The combination of OAuth tokens, account/zone/script bindings, and shell aliases produces silent failures that look like "the deploy worked" until you hit prod and see nothing changed. This skill is the catalog of those failures.
When to use
A wrangler command "succeeded" but the live behavior didn't change.
wrangler secret put NAME set the secret to an empty string.
D1 commands fail with auth errors only sometimes (the rest of wrangler works).
Custom domain configured days ago still 522s.
Hono c.redirect() followed by c.header('Set-Cookie', ...) "loses the cookie."
Worker hits CPU limit (1101) and you need to find the culprit.
Pages preview deploy + git-push production deploy collided.
Core capabilities
Wrangler auth model
Wrangler has two auth paths: OAuth (wrangler login) for human-driven local work, and API tokens (CLOUDFLARE_API_TOKEN) for CI. They have different scope models.
OAuth scopes are granted at first login. Adding a new product (D1, R2, Workers Logs) creates a new scope you don't have until you re-auth:
wrangler logout
wrangler login
# Opens browser; consent to the new scopes the prompt now lists.
If wrangler d1 execute returns Authentication error but wrangler whoami works, you're missing d1:write. Re-login.
For CI, mint an API token with the exact scopes:
Account → Workers Scripts → Edit
Account → D1 → Edit
Zone → DNS → Edit (only if you change DNS from CI)
Set as CLOUDFLARE_API_TOKEN; do not set CLOUDFLARE_API_KEY (legacy global).
The empty-secret trap
This bites at least once per project:
# WRONG — if `cat` is aliased (e.g. `cat → bat`), the pipe receives no bytes.cat /tmp/token.txt | wrangler secret put MY_TOKEN
# RIGHT — bypass aliases.
wrangler secret put MY_TOKEN < /tmp/token.txt
# OR
TOKEN=$(< /tmp/token.txt) && | wrangler secret put MY_TOKEN
printf
'%s'
"$TOKEN"
After uploading, verify the value isn't empty. Add a debug endpoint temporarily:
app.get('/_debug/secret-len', (c) => {
const v = c.env.MY_TOKEN ?? '';
return c.json({ len: v.length, type: typeof v });
});
Hit it; expect len > 0. Remove the endpoint before any non-trivial deploy.
D1 migrations vs "repair"
D1 has no migration repair analog because D1 doesn't pretend the SQL ran when it didn't. Compare:
Local vs remote: --local uses .wrangler/state/v3/d1/; --remote hits the real DB. Forgetting --remote is a frequent footgun.
Custom domains and routes
Two competing models in wrangler.toml:
# Model A — Cloudflare manages the DNS record on the zone.routes = [
{ pattern = "api.windags.ai", custom_domain = true }
]
# Model B — You own the DNS; route only triggers if traffic arrives.routes = [
{ pattern = "api.windags.ai/*", zone_name = "windags.ai" }
]
custom_domain = true creates an AAAA record on first deploy. If you rename the worker, the assignment doesn't migrate; you need to delete the old domain assignment in the dashboard and let the new worker re-create it.
Cookies on a 302
SameSite=Strict blocks cookies on redirects in some browsers (notably Safari and older Chrome). For login flows that POST or 302 into the protected zone, use SameSite=Lax:
Strict is appropriate for cookies that should never accompany a cross-origin navigation; Lax is the right default for session cookies that need to ride a top-level redirect.
Bindings that exist in the toml but not in the deploy artifact mean: you re-deployed without the new toml, or [env.staging] overrides shadowed it.
Workers limits
Plan
CPU per request
Memory
Subrequests
Free
10ms
128MB
50
Paid
30s
128MB
1000
Error 1101 = uncaught error during execution; 1102 = exceeded CPU. JSON.parse on a huge body, regex backtracking, and crypto.subtle calls on big inputs are common culprits.
Anti-patterns
Empty secret from piped cat (alias trap)
Symptom: Worker logs show secret_len=0 but wrangler secret list shows the secret name.
Diagnosis:cat aliased to a tool that's missing or expects a TTY. Pipe sends nothing; wrangler stores empty string.
Fix: Use < file redirect or printf '%s' "$VAR" | wrangler secret put NAME. Verify length after upload.
Wrangler OAuth missing D1 scope
Symptom: Workers/Pages commands work; wrangler d1 execute returns "Authentication error".
Diagnosis: OAuth was granted before D1 became part of the project; the scope wasn't re-consented.
Fix:wrangler logout && wrangler login. Consent to the now-listed scopes.
Re-deployed but route still hits old version
Symptom:wrangler deploy succeeded; live behavior unchanged.
Diagnosis: Custom domain still bound to the previous worker name, or a routes entry overlaps.
Fix: Dashboard → Workers & Pages → Triggers. Delete the stale assignment. Re-run wrangler deploy.
c.redirect() "losing" Set-Cookie
Symptom: Login endpoint sets cookie, redirects; the dashboard says forbidden.
Diagnosis: Hono DOES emit Set-Cookie on a redirect, but SameSite=Strict makes the browser drop the cookie on the immediate navigation.
Fix: Switch to SameSite=Lax for login-token cookies. Verify with curl + cookie jar to rule out server-side issues first.
Pages preview clobbered by git-push prod deploy
Symptom: A teammate's wrangler pages deploy preview is overwritten when main pushes.
Diagnosis: Both flows write to the same project. Production deploy from git is configured to consume the main branch.
Fix: Use distinct project names or branches. wrangler pages deploy out --project=foo-preview --branch=erich-test keeps previews isolated.
compatibility_date too old
Symptom:URLPattern is not defined; EventSource is undefined. Code that runs locally fails in production.
Diagnosis: Workers ships new APIs gated by compat date; old dates pin to old runtimes.
Fix: Bump compatibility_date to within the last 30 days. Add compatibility_flags only when you need a specific opt-in.
Quality gates
Every secret verified with a length-check endpoint or smoke test post-upload.
OAuth scopes refreshed whenever the project adds D1/R2/Queues.
D1 migrations applied with --remote; local + remote schemas reconciled before deploy.
Custom domain DNS resolves before the deploy is announced.
[observability] enabled = true in every environment.
compatibility_date bumped within 90 days of release.
Bindings enumerated at startup; missing bindings are loud, not silent.
No --no-verify or -c commit.gpgsign=false in deploy scripts unless explicitly authorized.
Error budget for CPU time monitored; 1102s tracked over time.
Deterministic Audit
Before a Workers/Pages deploy (or when reviewing another agent's deploy plan), write it
as a JSON object matching schemas/cloudflare-workers-debug-plan.schema.json and run it
through scripts/workers_debugging_audit.mjs:
auditWorkersDebugging(plan) encodes this skill's failure catalog and Quality Gates as
deterministic rules over structured fields — no keyword matching: OAuth used from CI,
the legacy global API key, secrets piped through an aliasable cat or never
length-verified, D1 commands without --remote, a renamed worker with a stale custom
domain assignment, [observability] off, a compatibility_date older than 90 days,
bindings never enumerated at startup, and a SameSite=Strict session cookie set on a
redirect. It returns { pass, score, findings, recommendations }.
examples/sample-input.json is a hardened CI deploy plan (pass: true) Version history lives in CHANGELOG.md.
NOT for
AWS Lambda / Vercel Edge / Deno Deploy — different runtimes, different limits.
R2 bucket-specific tuning — multipart, lifecycle, presigned URLs are a separate domain.
Cloudflare Zero Trust / Access — auth product with its own configuration model.
Hyperdrive-specific debugging — pair with the Hyperdrive skill (no dedicated skill yet).
Hono routing/middleware specifics — once it's a Hono issue, → hono-patterns.
