Migrate to Cloudflare Workers - Production Deployment Guide

I've migrated six production apps from Lambda to Workers over the past 18 months. Each time the pattern was the same: frustrated with cold starts killing user experience, fed up with paying for idle time, and sick of manually configuring regions.

The switch to V8 isolates instead of containers eliminates the cold start problem entirely. Lambda spins up a new container for every function call - Workers run your code in V8 isolates that start in under 5ms consistently.

What Actually Breaks During Migration

Node.js Compatibility Issues Hit Everyone:

• Filesystem APIs don't exist (fs.readFile, path.resolve)
• Some crypto operations use Node.js-specific implementations
• Native modules compiled for Node.js won't work
• Process environment variables work differently

I spent three days rewriting our image processing service because it relied heavily on filesystem operations. The fix was moving file operations to Cloudflare R2 and doing image transforms through Workers Image Resizing.

Lambda-Specific Code That Needs Rewrites:

• context.getRemainingTimeInMillis() doesn't exist
• Lambda event structures are different from Workers Request objects
• API Gateway integration assumes Lambda's response format
• CloudWatch logging calls won't work

The 2025 Migration Advantage

Containers in Beta Changes Everything:
Since June 2025, you can run Docker containers on Workers for code that can't fit the V8 isolate model. This eliminates the biggest migration blocker - you can lift-and-shift Lambda functions that do heavy filesystem operations or use native libraries.

Workflows is Production Ready:
Step functions replacements are no longer beta. The durable execution engine handles multi-step processes with automatic retries and state persistence.

Production Monitoring Actually Works:
Workers Observability now includes real-time logs, distributed tracing, and error alerting that doesn't suck like early 2024.

Database Connections Stop Being Hell

Hyperdrive Fixed Connection Pooling:
Connection pooling to PostgreSQL actually works now. I've connected to Neon, Supabase, and PlanetScale without the connection limit nightmares that plague Lambda.

Lambda functions create new database connections for every invocation. With 1000 concurrent requests, you hit connection limits immediately. Hyperdrive pools connections properly and maintains them across requests.

D1 for Edge-Native Storage:
D1 SQLite database replicates globally. Queries run locally instead of round-tripping to us-east-1. For session storage and configuration data, it's faster than DynamoDB and costs less.

Real Production Migration Timeline

Week 1: Assessment and Setup

• Audit Lambda functions for Node.js compatibility issues
• Set up Wrangler CLI and local development
• Migrate environment variables to Workers secrets

Week 2-3: Code Migration

• Rewrite filesystem operations to use R2 or external APIs
• Replace CloudWatch logging with Workers logging
• Convert Lambda event handlers to Workers Request/Response pattern
• Set up staging environment

Week 4: Production Deployment

• Blue-green deployment with gradual traffic shifting
• Monitor performance with Workers Analytics
• Configure custom domains and SSL

The Lambda Bill Reality Check

Lambda charges for wall-clock time - even when your function sits idle waiting for database queries. Workers charge for CPU time only. If your function spends 80% of its time waiting for I/O, you pay for 80% less compute.

I've seen monthly AWS bills drop from $2,400 to $890 just from switching I/O-heavy API endpoints. The free tier is generous too: 100k requests daily covers most side projects.

Global deployment happens automatically. Lambda makes you choose regions and manage deployments manually. Workers deploy to 330+ locations without configuration.

Migration Gotchas That Bite Everyone

Memory Limits Will Surprise You:
Workers get 128MB memory in the free tier, 128MB-1GB paid. Lambda goes up to 10GB. If you're processing large datasets in memory, you'll hit limits fast.

Execution Time Constraints:
30 seconds free, 15 minutes paid maximum. Long-running data processing jobs need to be redesigned or moved to Workers Containers.

Local Development Differences:
Miniflare local development is good but not perfect. I've hit cases where code works locally but fails on the edge. Budget extra testing time.

When Workers Isn't The Right Choice

Heavy Computation:
Workers excel at I/O-bound workloads (APIs, webhooks, edge logic). For CPU-intensive tasks like video processing or machine learning inference, Lambda or ECS might be better fits.

Filesystem Dependencies:
If your Lambda function relies heavily on reading/writing local files and you can't refactor to use object storage, the migration complexity might not be worth it.

Team Familiarity:
If your team is deeply invested in AWS services and workflows, the learning curve and integration changes might outweigh the performance and cost benefits.

That said, Workers Containers launching in 2025 addresses most of these limitations. You can run traditional containerized applications while keeping the Workers development experience.

The Workers ecosystem matured significantly in 2025. Containers went live in June, Workflows hit GA in April, and the observability tools finally stopped sucking.

The Container Revolution Changes Everything

Before June 2025: Workers had strict limitations. No filesystem access, limited memory, V8 isolates only. Great for APIs and edge logic, but migrating complex Lambda functions was painful.

After June 2025: Workers Containers let you run Docker images with full Linux environments. Memory up to several GB, filesystem access, any runtime. The global deployment model stays the same - your containers run everywhere automatically.

I've been running a FastAPI Python application in production containers since the beta. Zero configuration for global deployment, automatic scaling to zero, and the familiar Workers development experience.

Production Deployment Architecture

Multi-Tier Application Pattern:

• Workers for edge logic, routing, authentication, caching
• Containers for heavy computation, legacy applications, complex dependencies
• D1/Hyperdrive for data persistence and connection pooling
• Workflows for multi-step processes and durable execution

This hybrid approach gives you the best of both worlds. Fast cold starts for most traffic, full runtime flexibility when you need it.

Real Production War Stories

API Gateway Replacement (8 months in production):
Migrated our Kong-based API gateway to Workers. Handles authentication, rate limiting, request routing, and A/B testing. Zero downtime incidents since deployment, which is more than our Kong setup achieved.

The custom domain configuration was straightforward. SSL certificates auto-renew, WAF protection is built-in, and traffic routing happens instantly without API Gateway cold starts.

Background Job Processing:
Workflows replaced our SQS + Lambda setup for order processing. The waitForEvent API lets workflows pause for external events like payment webhooks.

Three-step order process: inventory check, payment processing, fulfillment. If payment fails, only the payment step retries - no duplicated inventory reservations. State persistence happens automatically.

Monitoring and Observability Setup

Real-Time Debugging:

## Live tail logs from any Worker
wrangler tail my-api --format pretty

## Filter errors only
wrangler tail my-api --status error

Workers Logpush sends structured logs to external systems. I pipe them to Datadog for correlation with application metrics and user behavior.

Performance Monitoring:

• Workers Analytics tracks request latency and success rates
• Real User Monitoring measures actual user experience
• Custom metrics via Worker Trace Events

Database Strategy for Production

Edge-First Data Architecture:

• D1 SQLite for configuration, sessions, small datasets
• Hyperdrive for connection pooling to PostgreSQL/MySQL
• KV for caching and eventually consistent data
• R2 for file storage with event notifications

D1's global read replicas eliminate database latency for read-heavy workloads. Writes go to primary, reads serve locally. Works great for user profiles and app configuration.

Deployment Pipeline That Doesn't Suck

Environment Strategy:

{
  "environments": {
    "staging": {
      "name": "my-api-staging",
      "vars": { "ENV": "staging" }
    },
    "production": {
      "name": "my-api-prod", 
      "vars": { "ENV": "production" }
    }
  }
}

CI/CD Pattern:

1. Wrangler in GitHub Actions for automated deployments
2. Preview deployments for every pull request
3. Gradual rollouts using traffic percentages
4. Automated rollback if error rates spike

The preview deployment URLs make code review easier. Reviewers can test actual functionality instead of just reading code.

Security in Production

Workers WAF Blocks Attacks Automatically:

• DDoS protection at Layer 3/4 and Layer 7
• OWASP Top 10 protection with managed rules
• Custom WAF rules for application-specific threats
• Bot protection that actually works

Secrets Management Done Right:

## Store secrets encrypted at rest
wrangler secret put DATABASE_URL
wrangler secret put STRIPE_SECRET_KEY

## Audit secret access
wrangler secret list

Workers secrets are only decrypted at runtime in your Worker. They don't appear in logs or debugging output. Much better than Lambda environment variables.

The Vendor Lock-In Question

Code Portability:
Standard JavaScript/TypeScript Workers code runs on Deno Deploy and Vercel Edge Functions with minimal changes. The Web APIs are increasingly standardized.

Platform-Specific APIs Create Lock-In:

• D1, KV, Durable Objects are Cloudflare-only
• Workflows API is proprietary (though similar to other durable execution engines)
• Workers Containers use standard Docker but the orchestration layer is custom

My Take: The performance and developer experience benefits outweigh lock-in concerns for most applications. If portability is critical, stick to standard Web APIs and external databases.

Cost Optimization in Production

Understand CPU vs Wall-Clock Billing:
Workers charge for CPU time only - time actually executing JavaScript. Database queries, API calls, and file operations don't count toward CPU usage.

Real Cost Example:

• Request takes 500ms total
• 450ms waiting for database query
• 50ms actual JavaScript execution
• You pay for 50ms, not 500ms

This makes Workers significantly cheaper than Lambda for I/O-heavy workloads. Our monthly compute bill dropped 60% migrating API endpoints that spend most time waiting on external services.

What's Coming in Late 2025

Enhanced Container Support:
GPU access for AI workloads, larger memory limits, and better local development experience. The container platform roadmap includes multi-container applications and service mesh capabilities.

Workflows Improvements:
More event sources, enhanced debugging tools, and human-in-the-loop capabilities. The waitForEvent API already supports external webhooks and manual approvals.

Better Observability:
Distributed tracing across Workers, Containers, and external services. Real-time performance insights and automated anomaly detection.

Workers in 2025 isn't the same platform as 2023. The container and workflow additions transformed it from "Lambda alternative" to "full-stack platform." If you evaluated Workers before and decided against it, the limitations you hit probably don't exist anymore.

Three years running Workers in production teaches you where the bodies are buried. Here's what actually goes wrong and how to fix it when you're debugging at 3am. These issues come up repeatedly in the Workers community forums and GitHub discussions.

Memory Limit Hell

Error: Error: Script exceeded memory limit

What happened: Your Worker hit the 128MB memory limit. This happens when processing large JSON responses, building big objects in memory, or trying to buffer entire file uploads. Check the Workers runtime limits documentation for current restrictions.

The fix that actually works:

// Bad - loads entire response into memory
const response = await fetch('https://api.example.com/huge-dataset');
const data = await response.json(); // 💥 Memory limit exceeded

// Good - stream and process incrementally  
const response = await fetch('https://api.example.com/huge-dataset');
const reader = response.body.getReader();
// Process chunks without loading everything

Production pattern: Use streaming APIs for large data processing. Move heavy operations to Workers Containers with higher memory limits.

The Node.js Compatibility Trap

Error: TypeError: fs.readFileSync is not a function

What happened: You're trying to use Node.js filesystem APIs that don't exist in the Workers runtime. This bites everyone migrating from Lambda. See the Node.js compatibility reference for what's supported and the migration guide for alternatives.

Common breaking patterns:

// All of this breaks in Workers
const fs = require('fs');
const path = require('path');
const os = require('os');
const crypto = require('crypto').scryptSync;

The migration fix:

// Use Web APIs instead
const data = await env.MY_BUCKET.get('file.json');
const url = new URL('./config.json', import.meta.url);
const hash = await crypto.subtle.digest('SHA-256', buffer);

Reality check: Budget 2x the time you think Node.js compatibility issues will take. The runtime differences are subtle but everywhere.

Database Connection Explosions

Error: Error: Too many connections or timeouts on database queries

What happened: Each Worker invocation tried to create a new database connection. Under load, you hit connection limits fast.

The wrong fix: Connection pooling in Worker code doesn't work because Workers are stateless.

The right fix: Hyperdrive for connection pooling to PostgreSQL/MySQL:

// Configure Hyperdrive binding
const result = await env.HYPERDRIVE.prepare(
  'SELECT * FROM users WHERE id = ?'
).bind(userId).first();

For SQLite: Use D1 which handles connections automatically:

const result = await env.DB.prepare(
  'SELECT * FROM users WHERE id = ?'
).bind(userId).first();

The Dreaded "Script exceeded execution time"

Error: Error: Script exceeded CPU time limit

What happens: Your Worker hit the CPU time limit (10ms free, 30ms paid). This is actual JavaScript execution time, not wall-clock time. Read about CPU time vs wall-clock billing to understand the difference.

Sneaky causes:

• Large JSON.parse() operations
• Heavy regex processing
• Synchronous crypto operations
• Building huge response objects

The fix:

// Bad - synchronous and CPU heavy
const result = heavyProcessingFunction(largeData);

// Good - break into chunks with async breaks
async function processInChunks(data) {
  for (let i = 0; i < data.length; i += CHUNK_SIZE) {
    processChunk(data.slice(i, i + CHUNK_SIZE));
    await new Promise(resolve => setTimeout(resolve, 0)); // Yield control
  }
}

Production reality: If you're hitting CPU limits regularly, move the processing to Workers Containers or redesign for streaming.

Cache Headers Fucking Up Everything

Problem: Workers responses getting cached when they shouldn't, or not cached when they should.

What's actually happening: Cloudflare's edge cache respects HTTP cache headers. Your Worker response gets cached globally if you don't set proper headers. Learn about cache control in Workers and cache debugging techniques.

The debug command that saves your sanity:

curl -H "CF-Cache-Status: true" YOUR_WORKER_URL
## Check the CF-Cache-Status header in response

Header patterns that work:

// Don't cache dynamic responses
return new Response(data, {
  headers: {
    'Cache-Control': 'no-cache, no-store, must-revalidate',
    'Content-Type': 'application/json'
  }
});

// Cache static responses for 1 hour
return new Response(staticData, {
  headers: {
    'Cache-Control': 'public, max-age=3600',
    'Content-Type': 'application/json'
  }
});

Environment Variables That Just Don't Work

Problem: Environment variables work locally with wrangler dev but undefined in production.

What's wrong: Workers uses secrets and environment variables differently than Lambda.

Local vs production mismatch:

## This works locally but not in prod
wrangler dev --env staging

## You need to actually set the secret
wrangler secret put DATABASE_URL --env staging

Debug pattern:

export default {
  async fetch(request, env) {
    // Log available env vars (remove before production!)
    console.log('Available env vars:', Object.keys(env));
    
    if (!env.DATABASE_URL) {
      return new Response('DATABASE_URL not configured', { status: 500 });
    }
  }
}

Durable Objects State Corruption

Error: Durable Object responses inconsistent or throwing serialization errors

What happened: You're trying to store non-serializable data in Durable Object storage, or hitting race conditions.

Common patterns that break:

// Bad - functions can't be serialized
await this.ctx.storage.put('callback', () => {});

// Bad - race condition
const value = await this.ctx.storage.get('counter') || 0;
await this.ctx.storage.put('counter', value + 1); // 💥 Race condition

Correct patterns:

// Good - atomic operations
await this.ctx.storage.transaction(async (txn) => {
  const value = await txn.get('counter') || 0;
  await txn.put('counter', value + 1);
});

// Good - serializable data only
await this.ctx.storage.put('config', JSON.stringify(configObject));

Request Body Parsing Nightmares

Error: TypeError: Cannot read property of undefined when parsing request bodies

What's happening: Different content types need different parsing methods, and the Worker runtime is stricter than Node.js.

The patterns that work:

export default {
  async fetch(request) {
    const contentType = request.headers.get('content-type');
    
    if (contentType?.includes('application/json')) {
      try {
        const body = await request.json();
        return handleJSON(body);
      } catch (e) {
        return new Response('Invalid JSON', { status: 400 });
      }
    }
    
    if (contentType?.includes('application/x-www-form-urlencoded')) {
      const formData = await request.formData();
      return handleForm(formData);
    }
    
    // Always handle the case where content-type is missing
    return new Response('Unsupported content type', { status: 400 });
  }
}

Local Dev vs Production Differences

Problem: Code works perfectly with wrangler dev but fails in production with cryptic errors.

Why this happens: Local development uses Node.js runtime, production uses V8 isolates. Subtle differences cause production-only failures. The local development guide explains these differences and the Wrangler documentation covers debugging options.

Patterns that expose the differences:

• Crypto operations that work locally but fail on edge
• Async/await timing differences
• Different error messages for the same failures
• Request/response header handling edge cases

The debugging approach:

## Deploy to staging frequently
wrangler deploy --env staging

## Use preview deployments for every change
wrangler deploy --compatibility-date=2024-09-23

## Tail production logs
wrangler tail my-worker --env production

When Workers Containers Fail to Start

Error: Container deployment succeeds but requests time out or return 502

What's actually wrong: Your container isn't listening on the port Workers expects, or it's not ready when traffic arrives.

Container debugging checklist:

## Make sure your app binds to 0.0.0.0, not localhost
EXPOSE 8080
CMD ["node", "server.js", "--host", "0.0.0.0", "--port", "8080"]

Health check pattern:

// In your Worker
export class MyContainer extends Container {
  async fetch(request) {
    // Add health check endpoint
    if (request.url.endsWith('/health')) {
      return new Response('OK', { status: 200 });
    }
    return super.fetch(request);
  }
}

Container logs debugging:

## Check container deployment status
wrangler containers list

## View container logs
wrangler containers logs my-container

The reality of running Workers in production: most issues are runtime differences from Node.js, memory management, or HTTP caching behavior. The platform is reliable, but the migration edge cases will bite you if you don't test thoroughly in staging first. For ongoing support, check the troubleshooting guide and join the Workers Discord community for real-time help.