Issue Review: cloudflare/workers-sdk#8714

Summary

Windows file paths with backslash-escape sequences (like \t in \thepl) are being interpreted as escape characters in error messages, causing paths to display incorrectly.

Findings

• Created: 2025-03-28
• Updated: 2025-10-30
• Version: 3.0.0-rc.0 → 4.60.0 (current)
• Component: wrangler (error formatting/display)
• Labels: bug
• Comments: 0

Key Evidence

• No PRs found that explicitly fix this issue (#8714)
• No changelog entries mention this issue
• Testing confirms esbuild's formatMessagesSync correctly preserves backslashes in Node.js
• The issue may be Windows-specific, potentially occurring in:
  • esbuild's Go binary output on Windows
  • Terminal escape sequence processing on Windows
  • Some serialization step not reproducible on macOS/Linux

Reproduction Analysis

The reporter clearly describes the bug: username thepl results in path \thepl where \t is interpreted as a tab character. The screenshot shows:

• Original path: C:\Users\thepl\AppData\Local\Temp\unterscale-jP6H51\wrangler.json
• Displayed path: C:\Users\[TAB]hepl\AppData\Local\Temp[TAB]unterscale-jP6H51\wrangler.json

My testing on macOS shows the path is preserved correctly through formatMessagesSync, suggesting this is Windows-specific behavior.

Recommendation

Status: KEEP OPEN

Reasoning: This is a real bug affecting Windows users whose paths contain characters that form escape sequences (\t, \n, \r, etc.). No fix has been merged, and the issue cannot be fully reproduced on non-Windows systems. The bug causes incorrect error messages that can confuse users trying to debug file path issues.

Action: Needs Windows-specific investigation and fix in the error formatting pipeline.

---

Root Cause Analysis

The error message is generated in packages/workers-utils/src/parse.ts:177 and packages/workers-utils/src/parse.ts:201:

throw new ParseError({
  text: `Could not read file: ${file}`,
  notes: [
    {
      text: message.replace(file, resolve(file)),
    },
  ],
  telemetryMessage: "Could not read file",
});

The file parameter contains the correct Windows path (with actual backslash characters, not escape sequences). The error is formatted through packages/wrangler/src/utils/format-message.ts:

export function formatMessage(
  { text, notes, location, kind = "error" }: Message,
  color = true
): string {
  const input = { text, notes, location };
  // ...
  const lines = formatMessagesSync([input], {
    color,
    kind: kind,
    terminalWidth: logger.columns,
  });
  return lines.join("\n");
}

The issue likely occurs in one of these locations:

1. esbuild's Go binary on Windows may process the message differently
2. Windows terminal escape sequence interpretation
3. ANSI color code processing combined with path characters

Proposed Solution

Option 1: Normalize paths to forward slashes in error messages (Recommended)

Modify the error creation to use forward slashes for display purposes:

// packages/workers-utils/src/parse.ts

function displayPath(filePath: string): string {
  // Convert backslashes to forward slashes for consistent display
  return filePath.replace(/\\/g, '/');
}

export function readFileSync(file: string): string {
  try {
    const buffer = fsReadFileSync(file);
    return removeBOMAndValidate(buffer, file);
  } catch (err) {
    if (err instanceof ParseError) {
      throw err;
    }

    const { message } = err as Error;
    throw new ParseError({
      text: `Could not read file: ${displayPath(file)}`,
      notes: [
        {
          text: message.replace(file, displayPath(resolve(file))),
        },
      ],
      telemetryMessage: "Could not read file",
    });
  }
}

Option 2: Escape backslashes in error messages

If preserving the native path format is preferred:

function escapePathForDisplay(filePath: string): string {
  // Double-escape backslashes to prevent interpretation
  return filePath.replace(/\\/g, '\\\\');
}

However, this would display C:\\Users\\thepl\\... which is less readable.

Implementation Difficulty

Easy

Justification:

• Single file modification required
• No complex logic or dependencies
• Clear fix with predictable behavior
• Low risk of regression

Files to Modify

1. packages/workers-utils/src/parse.ts - Add path display helper and use it in error messages
2. packages/wrangler/src/utils/format-message.ts (optional) - Could add path normalization at the formatting layer instead

Testing Recommendations

1. Unit tests - Add tests for path normalization/escaping function
2. Integration tests - Add Windows-specific tests that verify paths containing escape sequence characters (\t, \n, \r, \b, \f) are displayed correctly
3. Manual testing on Windows - Test with usernames/paths containing:
   • thepl (contains \t)
   • neil (contains \n)
   • robin (contains \r)
   • bob (contains \b)
   • fred (contains \f)

Suggested Comment

Thank you for reporting this issue! We've verified this is a real bug affecting Windows users whose paths contain characters that form escape sequences (like \t in your username).

The issue appears to be in how error messages with file paths are processed on Windows. We're tracking this for a fix that will normalize paths in error messages.

As a workaround, you can try setting an environment variable to use a different temp directory that doesn't contain escape sequence characters, or use a different Windows user profile for development.