pnpm dev fails on Windows with spawn EINVAL

Open Beginner friendly
#182 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Quiet
Tech stack
javascript, nodejs
Domain
devops, tooling

Research direction

Start in scripts/dev.mjs, focusing on run() and the platform-specific pnpm command resolution. Reproduce with pnpm dev on Windows, then verify that only batch-file commands use shell handling while docker and POSIX execution retain their current behavior. Done means the development stack starts and the friendly startup error handling remains usable.

Written by the indexing model from the issue text.

Description

Summary

pnpm dev cannot start the stack on Windows. It fails immediately with Error: spawn EINVAL before Postgres, the API, the gateway or the web app come up.

Environment

  • Windows 10 (10.0.26200), PowerShell
  • Node v22.23.2
  • pnpm 11.20.0
  • facility at ae68401

Reproduction

pnpm dev

Actual

Error: spawn EINVAL
    at ChildProcess.spawn (node:internal/child_process:420:11)
    at spawn (node:child_process:787:9)
  errno: -4071,
  code: 'EINVAL',
  syscall: 'spawn'

Expected

The development stack starts, as it does on macOS and Linux.

Root cause

scripts/dev.mjs resolves the package manager to a batch file on Windows:

const pnpm = process.platform === "win32" ? "pnpm.cmd" : "pnpm";

but run() spawns it without a shell:

const child = spawn(command, args, { cwd, env: environment, stdio: "inherit" });

Since Node 18.20 / 20.12 (the fix for CVE-2024-27980), child_process.spawn refuses to launch a .cmd or .bat file unless shell is set, and raises EINVAL.

Every pnpm invocation in the script is affected: pnpm install, the shared-package build, @facility/db migrate, @facility/db seed, and pnpm run dev:services. The first one aborts the run.

A secondary effect: spawn throws synchronously here, so the child.once("error", ...) handler in run() never runs and the friendly Could not start <label> hint is replaced by a raw stack trace, which makes the failure harder to diagnose than it needs to be.

Minimal confirmation on the same machine:

pnpm.cmd no-shell (current)  : SYNC THROW code=EINVAL
pnpm.cmd shell:true          : exited code=0
docker   no-shell            : exited code=0

docker is unaffected because it is a real executable, so the fix should be narrow rather than applying a shell to every spawn.

Suggested fix

Set shell only for .cmd and .bat commands on win32, leaving real executables and POSIX platforms with their current argument handling.

Happy to open a PR for this.

Dominant language
TypeScript
Stars
71
Forks
64
Avg merge
15h 38m
Merged PRs (30d)
66

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from theam/facility

All issues in theam/facility

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.