Skip to main content

Operations and Troubleshooting

Deploying code to a distributed edge network presents unique debugging challenges. When a Worker executes in a datacenter in Frankfurt, how do you see the console.log() output on your laptop in New York?

Learning Focus

By the end of this module, you will know how to stream live production logs, understand the strict resource limits imposed on Workers, and decipher common Error 1101 and 1042 exceptions.

1. Streaming Logs (wrangler tail)​

The primary tool for debugging a live production Worker is wrangler tail. It opens a WebSocket connection to Cloudflare's edge and streams console.log and console.error events directly to your terminal.

# Stream all logs from production
npx wrangler tail

# Format for JSON processing
npx wrangler tail --format=json

Limitations of tail​

  • Sampling: If your Worker receives 10,000 requests per second, tail will automatically sample the stream. You will not see every single request, to prevent crashing your local terminal.
  • Transience: The moment you close the terminal, the logs are gone. It is not persistent storage.

2. Persistent Logging (Logpush)​

For enterprise analytics, persistent debugging, or compliance, you must rely on Logpush.

Logpush automatically batches your Worker's console.log outputs and HTTP invocation metrics, and pushes them to a destination of your choice (like AWS S3, Datadog, or Cloudflare R2).

Note: Logpush is a paid feature available on the Cloudflare Enterprise or Workers Paid plans.

3. Strict Resource Limits​

Because Workers run in shared V8 Isolates, Cloudflare enforces extremely strict limits to prevent your code from monopolizing the host machine. Exceeding these limits instantly kills your Worker.

ResourceFree Plan LimitPaid Plan Limit
CPU Time10ms per request50ms - 30s (depending on usage model)
Memory128MB128MB
Subrequests50 per request1000 per request

CPU Time vs Wall Time​

CPU Time is the amount of time the processor is actively computing your JavaScript (like running a massive for loop or doing mathematical cryptography).

Wall Time is the total time the request takes.

If your Worker does this:

  1. Receives request. (0.1ms CPU)
  2. await fetch("http://slow-database") (Takes 5 seconds to reply)
  3. Returns response. (0.1ms CPU)

The total CPU time used is 0.2ms, meaning it easily passes the 10ms limit, even though the Wall Time was 5 seconds. V8 isolates yield the CPU while waiting for network I/O.

4. Common Exception Codes​

When a Worker crashes or exceeds its limits, Cloudflare intercepts the request and serves a standard HTML error page to the user. You must understand these error codes.

Error 1101: Worker threw exception​

The Worker executed, but the JavaScript code threw an unhandled error (e.g., trying to read a property of undefined, or a syntax error).

  • Fix: Run wrangler tail and trigger the route to see the exact JS stack trace.

Error 1102: Worker exceeded CPU time limit​

Your code spent too much time actively computing.

  • Fix: Offload heavy processing to traditional servers, or optimize your loops.

Error 1042: Worker tried to fetch itself​

Your Worker made a fetch(request.url) call that resolved back to the exact same Worker, creating an infinite loop. Cloudflare terminates this instantly.

  • Fix: Ensure any fetch() calls you make go to a different hostname or route.

Error 1015: Rate Limited​

You have hit the 100,000 requests/day limit on the Free tier.

  • Fix: Upgrade to the Paid ($5/mo) tier for 10M requests.

5. Source Maps in Production​

When wrangler deploy bundles your TypeScript code, it minifies the output. If a production error occurs, the stack trace might say: Error at Object.fetch (worker.js:1:3452)

To make sense of this, Wrangler automatically uploads Source Maps during deployment. When you view exceptions in the Cloudflare Dashboard, they will automatically be un-minified and map to your original .ts source files.

Conclusion of the Learning Path​

Congratulations! You have completed the Cloudflare Workers comprehensive guide.

You should now be comfortable scaffolding projects using wrangler, designing APIs with Hono, storing data in edge-native databases, and automating your pipelines using GitHub Actions.

Next Steps to Mastery:

  • Experiment with Durable Objects for a real-time chat application.
  • Build a full-stack Next.js or Remix application and deploy it via Cloudflare Pages (which runs on Workers under the hood).