AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/pages/gotchas.md

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)

| Resource | Free | Paid | |----------|------|------| | Functions Requests | 100k/day | Unlimited | | CPU Time | 10ms/req | 30ms/req | | Memory | 128MB | 128MB | | Script Size | 1MB | 10MB | | Subrequests | 50/req | 1,000/req | | Deployments | 500/month | 5,000/month |

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