Skillintermediate

Gotchas & Debugging

| Symptom | Likely Cause | Solution | |---------|--------------|----------| | **Function not invoking** | Wrong `/functions` location, wrong extension, or `_routes.json` excludes path | Check `pages_build_output_dir`, use `.js`/`.ts`, verify `_routes.json` | | **`ctx.env.BINDING` undefined** | Binding not configured or name mismatch | Add to `wrangler.jsonc`, verify exact name (case-sensitive), re

Claude Code Knowledge Pack7/10/2026

Overview

Gotchas & Debugging

Error Diagnosis

Symptom	Likely Cause	Solution
Function not invoking	Wrong `/functions` location, wrong extension, or `_routes.json` excludes path	Check `pages_build_output_dir`, use `.js`/`.ts`, verify `_routes.json`
`ctx.env.BINDING` undefined	Binding not configured or name mismatch	Add to `wrangler.jsonc`, verify exact name (case-sensitive), redeploy
TypeScript errors on `ctx.env`	Missing type definition	Run `wrangler types` or define `interface Env {}`
Middleware not running	Wrong filename/location or missing `ctx.next()`	Name exactly `_middleware.js`, export `onRequest`, call `ctx.next()`
Secrets missing in production	`.dev.vars` not deployed	`.dev.vars` is local only - set production secrets via dashboard or `wrangler secret put`
Type mismatch on binding	Wrong interface type	See api.md bindings table for correct types
"KV key not found" but exists	Key in wrong namespace or env	Verify namespace binding, check preview vs production env
Function times out	Synchronous wait or missing `await`	All I/O must be async/await, use `ctx.waitUntil()` for background tasks

Common Errors

TypeScript type errors

Problem: ctx.env.MY_BINDING shows type error
Cause: No type definition for Env
Solution: Run npx wrangler types or manually define:

interface Env { MY_BINDING: KVNamespace; }

Secrets not available in production

Problem: ctx.env.SECRET_KEY is undefined in production
Cause: .dev.vars is local-only, not deployed
Solution: Set production secrets:

echo "value" | npx wrangler pages secret put SECRET_KEY --project-name=my-app

Debugging

// Console logging

  console.log('Request:', ctx.request.method, ctx.request.url);
  const res = await ctx.next();
  console.log('Status:', res.status);
  return res;
}

# Stream real-time logs
npx wrangler pages deployment tail
npx wrangler pages deployment tail --status error

// Source maps (wrangler.jsonc)
{ "upload_source_maps": true }

Limits

Resource	Free	Paid
CPU time	10ms	50ms
Memory	128 MB	128 MB
Script size	10 MB compressed	10 MB compressed
Env vars	5 KB per var, 64 max	5 KB per var, 64 max
Requests	100k/day	Unlimited ($0.50/million)

Best Practices

Performance: Minimize deps (cold start), use KV for cache/D1 for relational/R2 for large files, set Cache-Control headers, batch DB ops, handle errors gracefully

Security: Never commit secrets (use .dev.vars + gitignore), validate input, sanitize before DB, implement auth middleware, set CORS headers, rate limit per-IP

Migration

Workers → Pages Functions:

export default { fetch(req, env) {} } → export function onRequest(ctx) { const { request, env } = ctx; }
Use _worker.js for complex routing: env.ASSETS.fetch(request) for static files

Other platforms → Pages:

File-based routing: /functions/api/users.js → /api/users
Dynamic routes: [param] not :param
Replace Node.js deps with Workers APIs or add nodejs_compat flag

Resources

See also: configuration.md for TypeScript setup | patterns.md for middleware/auth | api.md for bindings