1# Gotchas & Debugging
2 
3## Error Diagnosis
4 
5| Symptom | Likely Cause | Solution |
6|---------|--------------|----------|
7| **Function not invoking** | Wrong `/functions` location, wrong extension, or `_routes.json` excludes path | Check `pages_build_output_dir`, use `.js`/`.ts`, verify `_routes.json` |
8| **`ctx.env.BINDING` undefined** | Binding not configured or name mismatch | Add to `wrangler.jsonc`, verify exact name (case-sensitive), redeploy |
9| **TypeScript errors on `ctx.env`** | Missing type definition | Run `wrangler types` or define `interface Env {}` |
10| **Middleware not running** | Wrong filename/location or missing `ctx.next()` | Name exactly `_middleware.js`, export `onRequest`, call `ctx.next()` |
11| **Secrets missing in production** | `.dev.vars` not deployed | `.dev.vars` is local only - set production secrets via dashboard or `wrangler secret put` |
12| **Type mismatch on binding** | Wrong interface type | See [api.md](./api.md) bindings table for correct types |
13| **"KV key not found" but exists** | Key in wrong namespace or env | Verify namespace binding, check preview vs production env |
14| **Function times out** | Synchronous wait or missing `await` | All I/O must be async/await, use `ctx.waitUntil()` for background tasks |
15 
16## Common Errors
17 
18### TypeScript type errors
19 
20**Problem:** `ctx.env.MY_BINDING` shows type error  
21**Cause:** No type definition for `Env`  
22**Solution:** Run `npx wrangler types` or manually define:
23```typescript
24interface Env { MY_BINDING: KVNamespace; }
25export const onRequest: PagesFunction<Env> = async (ctx) => { /* ... */ };
26```
27 
28### Secrets not available in production
29 
30**Problem:** `ctx.env.SECRET_KEY` is undefined in production  
31**Cause:** `.dev.vars` is local-only, not deployed  
32**Solution:** Set production secrets:
33```bash
34echo "value" | npx wrangler pages secret put SECRET_KEY --project-name=my-app
35```
36 
37## Debugging
38 
39```typescript
40// Console logging
41export async function onRequest(ctx) {
42  console.log('Request:', ctx.request.method, ctx.request.url);
43  const res = await ctx.next();
44  console.log('Status:', res.status);
45  return res;
46}
47```
48 
49```bash
50# Stream real-time logs
51npx wrangler pages deployment tail
52npx wrangler pages deployment tail --status error
53```
54 
55```jsonc
56// Source maps (wrangler.jsonc)
57{ "upload_source_maps": true }
58```
59 
60## Limits
61 
62| Resource | Free | Paid |
63|----------|------|------|
64| CPU time | 10ms | 30s (default), 5min (max) |
65| Memory | 128 MB | 128 MB |
66| Script size | 10 MB compressed | 10 MB compressed |
67| Env vars | 5 KB per var, 64 max | 5 KB per var, 64 max |
68| Requests | 100k/day | Unlimited ($0.50/million) |
69 
70## Best Practices
71 
72**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
73 
74**Security:** Never commit secrets (use `.dev.vars` + gitignore), validate input, sanitize before DB, implement auth middleware, set CORS headers, rate limit per-IP
75 
76## Migration
77 
78**Workers → Pages Functions:**
79- `export default { fetch(req, env) {} }` → `export function onRequest(ctx) { const { request, env } = ctx; }`
80- Use `_worker.js` for complex routing: `env.ASSETS.fetch(request)` for static files
81 
82**Other platforms → Pages:**
83- File-based routing: `/functions/api/users.js` → `/api/users`
84- Dynamic routes: `[param]` not `:param`
85- Replace Node.js deps with Workers APIs or add `nodejs_compat` flag
86 
87## Resources
88 
89- [Official Docs](https://developers.cloudflare.com/pages/functions/)
90- [Workers APIs](https://developers.cloudflare.com/workers/runtime-apis/)
91- [Examples](https://github.com/cloudflare/pages-example-projects)
92- [Discord](https://discord.gg/cloudflaredev)
93 
94**See also:** [configuration.md](./configuration.md) for TypeScript setup | [patterns.md](./patterns.md) for middleware/auth | [api.md](./api.md) for bindings
95