windmill-labs/windmill · error

failed to run npm: ${e instanceof Error ? e.message : e} ${

Error message

failed to run npm: ${e instanceof Error ? e.message : e}

${HINT}

What it means

Thrown by the windmill CLI's `upgrade` function when the spawned npm process (used to install/update the CLI globally) emits an 'error' event instead of exiting — i.e. it could not be launched at all. The message embeds the underlying Node error and a HINT explaining how to upgrade manually.

Source

Thrown at cli/src/utils/upgrade.ts:105

    const output: string[] = [];
    proc.stdout?.on("data", (d) => {
      output.push(String(d));
      if (verbose) process.stdout.write(d);
    });
    proc.stderr?.on("data", (d) => {
      output.push(String(d));
      if (verbose) process.stderr.write(d);
    });
    // `error` fires when npm can't be spawned at all; without a listener that
    // is an uncaught exception, crashing before any hint prints. `close`
    // resolves null when npm died from a signal — a failure too.
    const exitCode: number | null = await new Promise<number | null>(
      (resolve, reject) => {
        proc.on("error", reject);
        proc.on("close", resolve);
      }
    ).catch((e) => {
      throw new Error(
        `failed to run npm: ${e instanceof Error ? e.message : e}\n\n${HINT}`
      );
    });
    if (exitCode !== 0) {
      const detail = output.join("").trim();
      throw new Error(
        `npm exited with ${
          exitCode === null ? "a signal" : `code ${exitCode}`
        }${detail ? `:\n${detail}` : ""}\n\n${HINT}`
      );
    }
  }
}

type NpmApiPackageMetadata = {
  "dist-tags": {
    latest: string;
  };

View on GitHub (pinned to e474e8803c)

Solutions

1. Install Node.js/npm and ensure `npm --version` works in the same shell
2. Reinstall the CLI manually with `npm install -g windmill-cli@latest` (see HINT in the message)
3. If using nvm, run `nvm use <version>` or add node to PATH before running `wmill upgrade`

Example fix

// before (npm missing)
wmill upgrade
// Error: failed to run npm: spawn npm ENOENT
// after
export PATH="$HOME/.nvm/versions/node/v20.11.0/bin:$PATH"
wmill upgrade

const hasNpm = spawnSync('npm', ['--version'], { stdio: 'ignore' }).status === 0;
if (!hasNpm) throw new Error('npm is not available on PATH; install Node.js first');

try {
  await upgrade();
} catch (e) {
  if (String(e.message).startsWith('failed to run npm:')) {
    console.error('npm could not be launched:', e.message);
    // fallback: manual install instructions
  } else throw e;
}

When it happens

Trigger: Calling `wmill upgrade` when npm is not installed or not on PATH, the npm binary lacks execute permission, or spawn fails for OS/arch reasons (e.g. nvm-managed node removed from PATH).

Common situations: Node installed via nvm/fnm and the current shell lacks the node path; Windows environments where 'npm' needs shell resolution; minimal Docker images without npm.

Related errors

• npm exited with ${exitCode === null ? "a signal" : `code ${e
• App ${appPath} not found
• wmill-lock.yaml is at unknown version "${conf.version}". Thi
• couldn't fetch the latest version - try again after sometime
• Error reading inline path: ${path}, ${error}

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/0f5d492f1461091c. Report an issue: GitHub.