Skip to content
Skills Library
Programming · Analysis

windows-npm-run-script-shell

/windows-npm-run-script-shell

Use when Windows npm run, npm test, npm run build, or npm run-script exits before running the script with ERR_INVALID_ARG_TYPE, "file argument must be of type string", missing ComSpec, broken script-shell, stripped CLI flags, sandboxed npm cache/log EPERM, or silent npm script output.

Repository
Noosphere ↗
Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

98/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when Windows npm run, npm test, npm run build, or npm run-script exits before running the script with ERR_INVALID_ARG_TYPE, "file argument must be of type string", missing ComSpec, broken script-shell, stripped CLI flags, sandboxed npm cache/log EPERM, or silent npm script output.

Triggers from the description

file argument must be of type string
Original author description

Use when Windows npm run, npm test, npm run build, or npm run-script exits before running the script with ERR_INVALID_ARG_TYPE, "file argument must be of type string", missing ComSpec, broken script-shell, stripped CLI flags, sandboxed npm cache/log EPERM, or silent npm script output.

How it works

  1. Overview
  2. Triage
  3. Fix
  4. Common Mistakes
  5. Completion Standard
Original SKILL.md headings · 71 lines, 389 words
SKILL.md preview
---
name: windows-npm-run-script-shell
description: Use when Windows npm run, npm test, npm run build, or npm run-script exits before running the script with ERR_INVALID_ARG_TYPE, "file argument must be of type string", missing ComSpec, broken script-shell, stripped CLI flags, sandboxed npm cache/log EPERM, or silent npm script output.
---

# Windows Npm Run Script Shell

## Overview

Windows npm scripts need a shell. If `ComSpec` is missing or npm cannot infer a script shell, `npm run ...` can fail inside npm before `tsc`, Vite, Vitest, or Playwright actually runs.

## Triage

Use this flow before changing app code:

1. Run the target tool directly with `npx`, for example `npx tsc -b --pretty false`, `npx vite build`, or `npx vitest run`.
2. Run `npm run <script> --loglevel verbose`.
3. Open the npm debug log if output is empty.
4. Check shell config:

```powershell
npm config get script-shell
npm config get cache
npm config get update-notifier
Write-Host "ComSpec=[$env:ComSpec]"
Write-Host "SHELL=[$env:SHELL]"
```

If direct `npx` commands pass but `npm run` fails with `ERR_INVALID_ARG_TYPE: The "file" argument must be of type string. Received undefined`, treat it as npm shell configuration, not a project build failure.

If direct `node <script>` succeeds but `npm test`/`npm run` exits silently in a sandbox, rerun with `--loglevel verbose`. When npm reports `EPERM` creating `%LocalAppData%\npm-cache\_logs` or attempts registry access only for update checks, treat it as npm runtime side effects, not a test failure.

## Fix

Prefer a project-local `.npmrc` so the fix travels with the repo:

```ini
script-shell=C:\Windows\System32\cmd.exe
```

For sandboxed Windows workspaces where npm cannot write the user cache/log directory, keep npm side effects inside the repo and disable network-prone notices:

```ini
cache=.npm-cache
update-notifier=false
fund=false
audit=false
script-shell=cmd.exe
```

Then rerun:

```powershell
npm run build
npm test -- --run
```

If the project requires PowerShell syntax in scripts, set `script-shell` to PowerShell and avoid `&&` in package scripts, because Windows PowerShell 5 does not support `&&`.

## Common Mistakes

- Do not rewrite TypeScript, Vite, Vitest, or React code when `npx <tool>` succeeds and only `npm run` fails.
- Do not treat silent npm output as proof that the build tool produced no diagnostics; inspect the npm debug log.
- Do not ignore npm cache/log `EPERM` in sandboxed workspaces; set a project-local cache before escalating.
- Do not set a global npm config unless the user asked for machine-wide changes.
- Do not assume `SHELL` replaces `ComSpec` for npm on Windows.

## Completion Standard

The issue is fixed only when:

- The original `npm run <script>` command succeeds.
- The direct tool command still succeeds.
- Tests/builds that previously passed via `npx` also pass through npm scripts.

Versions

The database has no other skills named windows-npm-run-script-shell.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version fff79e512ea0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86npm-release-check
    Check an npm package before it is released. Use when the user is about to release a package to npm, bump a version, or asks whether a package is ready to ship. Runs one offline script that reads what npm pack would put in the tarball and reports secrets, private files, missing…
  • 100deploy-npm
    Release an npm package: version, CHANGELOG, publish, verify. Use when "publish this package", "release to npm", or "ship a new npm version". Running-app production deploy → workflow-ship-and-observe.
  • 100setup
    Set up the `clickhouse-js` repository in a fresh checkout so the agent can run tests, lints, type checks, builds, or examples. Use this skill before invoking any `npm run test:*`, `npm run lint`, `npm run typecheck`, `npm run build`, or `npm run run-examples` script — or after…
  • 100npm-publishing
    Publishing OCaml to npm via js_of_ocaml and wasm_of_ocaml. Use when discussing browser targets, JavaScript compilation, WASM output, npm packages, or the two-branch workflow.
  • 100review-shell-scripts
    Review all shell scripts against the Bash Script Convention. Use when you need to check script compliance or before committing changes.
  • 90windows-shell-rules-en
    Working rules for Claude Code on Windows - plain ASCII file names, UTF-8 when saving text, quoted paths with spaces, check which shell will run a command (PowerShell vs Git Bash), one task per conversation. Use whenever you create files or folders, save non-English text, or run…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.