Worker and Pages Debugging

Learning Focus

By the end of this lesson you will be able to debug edge functions in real-time using logs, identify common runtime errors, and set up automated error monitoring.

The Debugging Workflow

Debugging at the edge is different from local debugging. Because your code runs in 330+ cities, you need tools that can aggregate and stream logs back to you in real-time.

flowchart LR
    EDGE["Cloudflare Edge\n(330+ Cities)"] -->|"Stream Logs"| WRANGLER["Your Terminal\n(wrangler tail)"]
    EDGE -->|"Log Aggregation"| DASHBOARD["Cloudflare Dashboard\n(Real-time Logs)"]

    style EDGE fill:#f6821f,color:#fff,stroke:#e5711e
    style WRANGLER fill:#2563eb,color:#fff,stroke:#1e40af

Real-Time Logging with wrangler tail

The fastest way to see what's happening in your Worker is to "tail" its logs. This opens a persistent connection that streams every console.log() and error from the edge to your terminal.

Start tailing your worker

wrangler tail my-worker

Advanced Tailing: Filtering by Error

# Only show requests that resulted in an error
wrangler tail my-worker --status error

Metrics and Json output

# Output logs in JSON for processing with tools like jq
wrangler tail my-worker --format json | jq .

Dashboard Log Viewer

If you prefer a UI, use the Real-time Log Viewer in the dashboard:

1. Go to Workers & Pages → Your Worker → Logs.
2. Click "Begin Log Stream".
3. You will see requests, status codes, and console output in real-time.

Retention

Free tier logs are ephemeral — they are not stored. They are only available while you are actively tailing or viewing the stream.

Common Worker Errors

Error	Meaning	Common Cause
1101	Worker Threw Exception	Unhandled JavaScript error in your code
1102	CPU Limit Exceeded	Your logic took >10ms (Free) or >50ms (Paid) of CPU time
1015	Rate Limited	You hit a Cloudflare rate limit (e.g. for subrequests)
1042	Script Not Found	Deployment issue or internal Cloudflare error

Debugging CPU Limits (1102)

If you hit the 10ms CPU limit:

• Use performance.now() to profile sections of your code.
• Avoid heavy loops or complex cryptographic operations in a Worker.
• Offload work to Queues if possible.

Testing with wrangler dev

Before deploying, always test locally using wrangler dev.

Mode	Command	Behavioral Details
Local Mode	wrangler dev --local	Runs in a local Node.js environment. Fastest.
Remote Mode	wrangler dev	Runs in a real Cloudflare preview isolate. Most accurate.

tip

Always use Remote Mode (wrangler dev) for final testing before deployment. Some things (like specific request.cf properties) only exist in the real Cloudflare environment.

Automated Error Monitoring

For production apps, you need to know when things break even when you aren't tailing logs.

1. Sentry: Use the @sentry/cloudflare SDK to capture exceptions.
2. Workers Analytics Engine: Log custom metrics and error counts for dashboard visualization.
3. Logpush (Paid): Export all logs to S3, Datadog, or Honeycomb for long-term storage and analysis.

Key Takeaways

• Use wrangler tail for the fastest real-time debugging from the terminal.
• The Dashboard Log Viewer provides a UI-based stream of requests and console output.
• Error 1101 is almost always a bug in your JavaScript code.
• Error 1102 means your CPU usage exceeded the plan's limit.
• Remote Mode (wrangler dev) is the most accurate representation of the live environment.

What's Next

• Continue to Reference and Cheatsheet for a full list of error codes and CLI commands.