Debugging Workers with Wrangler: A Practical Guide

Previously in this course, we covered Handling HTTP Requests: A Developer’s Guide to Workers, where you learned to intercept and modify traffic. While building features is satisfying, inevitably, code will behave unexpectedly. In this lesson, we shift our focus to Debugging, providing you with the tools to troubleshoot and monitor your Worker scripts effectively.

The Philosophy of Edge Debugging

Debugging on the edge is fundamentally different from a traditional local server. You cannot "attach" a debugger to a process running on thousands of servers globally. Instead, you rely on two pillars: Local Simulation (reproducing the issue on your machine) and Remote Observability (inspecting what happened in production).

1. Local Simulation with Wrangler

Before you ever push code to the edge, you should test it locally. Wrangler provides a robust simulation environment that mimics the Cloudflare runtime.

When you run wrangler dev, you aren't just running a Node.js script; you are running an emulation of the V8 isolate environment that Cloudflare uses.

Worked Example: Inspecting Requests Let’s create a simple debug scenario where we inspect incoming headers. Update your index.js (or worker.js):

JAVASCRIPT
export default {
  async fetch(request, env, ctx) {
    // Log the entire request object to the terminal
    console.log("Incoming request URL:", request.url);
    console.log("Request Headers:", JSON.stringify([...request.headers]));

    if (request.headers.get("x-debug-mode") === "true") {
      return new Response("Debug mode is active", { status: 200 });
    }

    return new Response("Hello World!", { status: 200 });
  },
};

Run this with wrangler dev. When you open your browser or use curl to hit http://localhost:8787, watch your terminal. You will see the console.log output printed directly in the Wrangler process window. This is your primary feedback loop.

2. Mastering console.log

In the Workers environment, console.log is your best friend. It supports structured logging, meaning you can pass objects, and they will be serialized for your review.

Common Pitfall: The "Silent" Failure A common mistake is assuming that console.log will always appear in the dashboard immediately. In high-traffic production environments, logs are sampled and buffered. If you are debugging a transient issue, use the --tail command to view logs in real-time:

Bash
wrangler tail my-worker-name

This command streams logs from the production edge directly to your local terminal, allowing you to see exactly what is happening as requests hit your script.

3. Dashboard Inspection

Sometimes you need to look at historical data rather than live streams. The Cloudflare Dashboard provides a "Logs" tab under your Worker's settings.

To see these logs, navigate to: Cloudflare Dashboard > Workers & Pages > [Your Worker] > Logs.

Ensure you have "Log push" enabled if you are on a paid plan, or simply use the real-time tailing feature provided by the CLI for free-tier development.

Hands-on Exercise: Debugging a "Broken" Request

1. Modify your local Worker to throw an intentional error if a specific header is missing:

   JAVASCRIPT
   if (!request.headers.get("user-agent")) {
     throw new Error("Missing User-Agent header!");
   }
   

2. Run wrangler dev and send a request using curl -H "User-Agent:" http://localhost:8787.
3. Observe the stack trace in your terminal.
4. Practice using console.log before the if statement to log the request object so you can see exactly why the check failed.

Common Pitfalls

• Forgetting to stringify: Passing a deep object to console.log might result in [object Object] in some environments. Always use JSON.stringify(obj, null, 2) for readable output.
• Ignoring the Context: Remember that ctx.waitUntil() is used for asynchronous tasks. If your background tasks fail, they won't show up in your main request logs unless you explicitly log inside the waitUntil function.
• Over-logging: In production, excessive logging can impact performance. Use a conditional check—like checking for a debug header—before firing heavy log statements.

FAQ

Q: Can I use breakpoints like in VS Code? A: Not directly in the traditional sense. Because the code runs on remote edge nodes, you cannot pause the execution flow of live production traffic. Stick to console.log and log-based tracing.

Q: Why don't I see my logs in the dashboard? A: Ensure you have initialized your project correctly as covered in Introduction to Wrangler CLI. If you're on the free plan, make sure you are using wrangler tail for live inspection rather than expecting long-term log storage.

Recap

Debugging is about visibility. By mastering console.log, utilizing wrangler dev for local simulation, and employing wrangler tail for production-level inspection, you can cut your troubleshooting time significantly. You are now equipped to trace execution flow and identify bottlenecks in your Workers.

Up next: Project Milestone: The Edge Interceptor, where we will apply these debugging skills to build a functional middleware that modifies site headers in real-time.