Cloudflare

Gotchas

Functions Not Running

Problem: Function endpoints return 404 or don't execute Causes: _routes.json excludes path; wrong file extension (.jsx/.tsx); Functions dir not at output root Solution: Check _routes.json, rename to .ts/.js, verify build output structure

404 on Static Assets

Problem: Static files not serving Causes: Build output dir misconfigured; Functions catching requests; Advanced mode missing env.ASSETS.fetch() Solution: Verify output dir, add exclusions to _routes.json, call env.ASSETS.fetch() in _worker.js

Bindings Not Working

Problem: env.BINDING undefined or errors Causes: wrangler.jsonc syntax error; wrong binding IDs; missing .dev.vars; out-of-sync types Solution: Validate config, verify IDs, create .dev.vars, run npx wrangler types

Build Failures

Problem: Deployment fails during build Causes: Wrong build command/output dir; Node version incompatibility; missing env vars; 20min timeout; OOM Solution: Check Dashboard → Deployments → Build log; verify settings; add .nvmrc; optimize build

Middleware Not Running

Problem: Middleware doesn't execute Causes: Wrong filename (not _middleware.ts); missing onRequest export; didn't call next() Solution: Rename file with underscore prefix; export handler; call next() or return Response

Headers/Redirects Not Working

Problem: _headers or _redirects not applying Causes: Only work for static assets; Functions override; syntax errors; exceeded limits Solution: Set headers in Response object for Functions; verify syntax; check limits (100 headers, 2,100 redirects)

TypeScript Errors

Problem: Type errors in Functions code Causes: Types not generated; Env interface doesn't match wrangler.jsonc Solution: Run npx wrangler types --path='./functions/types.d.ts'; update Env interface

Local Dev Issues

Problem: Dev server errors or bindings don't work Causes: Port conflict; bindings not passed; local vs HTTPS differences Solution: Use --port=3000; pass bindings via CLI or wrangler.jsonc; account for HTTP/HTTPS differences

Performance Issues

Problem: Slow responses or CPU limit errors Causes: Functions invoked for static assets; cold starts; 10ms CPU limit; large bundle Solution: Exclude static via _routes.json; optimize hot paths; keep bundle < 1MB

Framework-Specific

⚠️ Deprecated Frameworks

Next.js: Official adapter (@cloudflare/next-on-pages) deprecated and unmaintained.

• Problem: No updates since 2024; incompatible with Next.js 15+; missing App Router features

• Cause: Cloudflare discontinued official support; community fork exists but limited

• Solutions:

  1. Recommended: Use Vercel (official Next.js host)

  2. Advanced: Self-host on Workers using custom adapter (complex, unsupported)

  3. Migration: Switch to SvelteKit/Nuxt (similar DX, full Pages support)

Remix: Official adapter (@remix-run/cloudflare-pages) deprecated.

• Problem: No maintenance from Remix team; compatibility issues with Remix v2+

• Cause: Remix team deprecated all framework adapters

• Solutions:

  1. Recommended: Migrate to SvelteKit (similar file-based routing, better DX)

  2. Alternative: Use Astro (static-first with optional SSR)

  3. Workaround: Continue using deprecated adapter (no future support)

✅ Supported Frameworks

SvelteKit:

• Use @sveltejs/adapter-cloudflare

• Access bindings via platform.env in server load functions

• Set platform: 'cloudflare' in svelte.config.js

Astro:

• Built-in Cloudflare adapter

• Access bindings via Astro.locals.runtime.env

Nuxt:

• Set nitro.preset: 'cloudflare-pages' in nuxt.config.ts

• Access bindings via event.context.cloudflare.env

Qwik, Solid Start:

• Built-in or official Cloudflare adapters available

• Check respective framework docs for binding access

Debugging

// Log request details
console.log('Request:', { method: request.method, url: request.url });
console.log('Env:', Object.keys(env));
console.log('Params:', params);

View logs: npx wrangler pages deployment tail --project-name=my-project

Smart Placement Issues

Increased Cold Start Latency

Problem: First requests slower after enabling Smart Placement Cause: Initial optimization period while system learns traffic patterns Solution: Expected behavior during first 24-48 hours; monitor latency trends over time

Inconsistent Response Times

Problem: Latency varies significantly across requests during initial deployment Cause: Smart Placement testing different execution locations to find optimal placement Solution: Normal during learning phase; stabilizes after traffic patterns emerge (1-2 days)

No Performance Improvement

Problem: Smart Placement enabled but no latency reduction observed Cause: Traffic evenly distributed globally, or no data locality constraints Solution: Smart Placement most effective with centralized data (D1/DO) or regional traffic; disable if no benefit

Remote Bindings Issues

Accidentally Modified Production Data

Problem: Local dev with --remote altered production database/KV Cause: Remote bindings connect directly to production resources; writes are real Solution:

• Use --remote only for read-heavy debugging

• Create separate preview environments for testing

• Never use --remote for write operations during development

Remote Binding Auth Errors

Problem: npx wrangler pages dev --remote fails with "Unauthorized" or auth error Cause: Not logged in, session expired, or insufficient account permissions Solution:

1. Run npx wrangler login to re-authenticate

2. Verify account has access to project and bindings

3. Check binding IDs match production configuration

Slow Local Dev with Remote Bindings

Problem: Local dev server slow when using --remote Cause: Every request makes network calls to production bindings Solution: Use local bindings for development; reserve --remote for final validation

Common Errors

"Module not found"

Cause: Dependencies not bundled or build output incorrect Solution: Check build output directory, ensure dependencies bundled

"Binding not found"

Cause: Binding not configured or types out of sync Solution: Verify wrangler.jsonc, run npx wrangler types

"Request exceeded CPU limit"

Cause: Code execution too slow or heavy compute Solution: Optimize hot paths, upgrade to Workers Paid

"Script too large"

Cause: Bundle size exceeds limit Solution: Tree-shake, use dynamic imports, code-split

"Too many subrequests"

Cause: Exceeded 50 subrequest limit Solution: Batch or reduce fetch calls

"KV key not found"

Cause: Key doesn't exist or wrong namespace Solution: Check namespace matches environment

"D1 error"

Cause: Wrong database_id or missing migrations Solution: Verify config, run wrangler d1 migrations list

Limits Reference (Jan 2026)

Tip: Hitting CPU limit? Optimize hot paths or upgrade to Workers Paid plan.

Full limits

Getting Help

1. Check Pages Docs

2. Search Discord #functions

3. Review Workers Examples

4. Check framework-specific docs/adapters