← ./articles

Wrangler Pages Deploy Crashes on Windows? Check Non-ASCII CWD First

cloudflare-pageswranglerwindowsdeploymentnodejs

Wrangler Pages deploy can fail before it uploads anything.

On Windows, one under-documented cause is the process working directory itself. If Wrangler starts from a path containing non-ASCII characters, a native dependency can crash before the deploy target is even inspected.

This is easy to misdiagnose as a broken Cloudflare project, a bad Pages config, or a Wrangler version bug. The useful clue is where the command stops.

The symptom: Wrangler exits after the version header

The failure pattern is narrow:

  • npx wrangler pages deploy out --project-name my-site starts
  • Wrangler prints its version header
  • no file upload progress appears
  • Git Bash may show Segmentation fault
  • PowerShell may only return exit code 1
  • the same project builds successfully before deploy

That is different from a normal Pages deployment error. A normal deploy error usually happens after Wrangler has read files, contacted Cloudflare, or returned an API message.

Here, the process dies too early.

Why moving only the output directory may not fix it

The tempting fix is to copy out/ or dist/ to an ASCII-only directory and run:

npx wrangler pages deploy C:\tmp\site-out --project-name my-site

That can still crash if the Wrangler process itself is launched from the original project directory.

The deploy target path and the process current working directory are not the same thing. If the crash follows the process cwd, passing an ASCII deploy target is not enough.

Check both:

Get-Location
Test-Path out
npx wrangler pages deploy out --project-name my-site

If Get-Location contains non-ASCII path segments and Wrangler dies before upload progress, test the cwd hypothesis before changing app code.

Confirm the cwd hypothesis

Use a clean ASCII directory and make it Wrangler's working directory.

The quick manual test is:

$stage = Join-Path $env:TEMP ("wrangler-pages-" + [DateTimeOffset]::Now.ToUnixTimeMilliseconds())
New-Item -ItemType Directory -Path $stage | Out-Null
Copy-Item -Recurse out\* $stage
Push-Location $stage
npx wrangler pages deploy . --project-name my-site
Pop-Location

If the deploy succeeds from $env:TEMP, the project source is probably not the cause. The failure is tied to the environment Wrangler was launched from.

Fix: stage output and spawn Wrangler from the staging directory

For a repeatable project script, stage the built files in an ASCII temp directory and run Wrangler with cwd set to that directory:

const fs = require("fs");
const os = require("os");
const path = require("path");
const { spawnSync } = require("child_process");

const projectRoot = process.cwd();
const outDir = path.join(projectRoot, "out");
const stageDir = path.join(os.tmpdir(), `wrangler-pages-${Date.now()}`);

fs.cpSync(outDir, stageDir, { recursive: true });

try {
  const result = spawnSync(
    "npx",
    ["wrangler", "pages", "deploy", ".", "--project-name", "my-site"],
    {
      cwd: stageDir,
      stdio: "inherit",
      shell: process.platform === "win32",
    },
  );

  process.exitCode = result.status ?? 1;
} finally {
  fs.rmSync(stageDir, { recursive: true, force: true });
}

Then call that script after the build:

{
  "scripts": {
    "build": "next build",
    "pages:deploy": "node scripts/deploy-pages.js"
  }
}

The important part is not only copying the artifact. It is making the staged directory the current working directory for the Wrangler child process.

Verify the deployment instead of trusting one signal

After the staging fix, verify the actual Pages deployment:

npx wrangler pages deployment list --project-name my-site
Invoke-WebRequest https://my-site.pages.dev/ -UseBasicParsing

A deploy script should distinguish:

  • build failed before producing out/
  • Wrangler crashed before upload progress
  • Cloudflare rejected the upload
  • deploy completed but the CLI returned a confusing status
  • the live URL serves the expected artifact

Those are different failures. Treating all of them as "Cloudflare deploy broken" leads to unnecessary retries.

When this is not the right diagnosis

Do not force this explanation when:

  • Wrangler reaches upload progress and then returns an API error
  • the output directory is missing or stale
  • the project name is wrong
  • the account token lacks Pages permissions
  • the same command fails from a clean ASCII directory too

In those cases, use normal Cloudflare Pages debugging: check the output directory, Wrangler authentication, project name, and deployment logs.

References