{"record":{"id":"11a78947a6c27b44","repo":"JuliusBrussee/caveman","slug":"cannot-safely-launch-windows-command-shim-executable","errorCode":null,"errorMessage":"cannot safely launch Windows command shim: ${executable}","messagePattern":"cannot safely launch Windows command shim: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/portable-command.ts","lineNumber":65,"sourceCode":"      const candidate = join(directory, name);\n      if (existsSync(candidate)) return candidate;\n    }\n  }\n  return undefined;\n}\n\nexport function portableInvocation(\n  command: string,\n  args: readonly string[],\n  platform: NodeJS.Platform = process.platform,\n  env: NodeJS.ProcessEnv = process.env,\n): PortableInvocation {\n  if (platform !== \"win32\") return { command, args: [...args] };\n  const executable = resolveWindowsCommand(command, env) ?? command;\n  if (!/\\.(?:cmd|bat)$/i.test(executable)) return { command: executable, args: [...args] };\n  const stat = statSync(executable);\n  if (!stat.isFile() || stat.size > 256 * 1024) {\n    throw new Error(`cannot safely launch Windows command shim: ${executable}`);\n  }\n  const shimScript = parseWindowsNodeShim(readFileSync(executable, \"utf8\"));\n  if (!shimScript) {\n    throw new Error(`cannot safely launch non-Node Windows command shim: ${executable}; install a native .exe`);\n  }\n  const script = /^[A-Za-z]:[\\\\/]/.test(shimScript)\n    ? shimScript\n    : resolve(dirname(executable), ...shimScript.split(/[\\\\/]+/));\n  if (!statSync(script).isFile()) {\n    throw new Error(`Windows command shim target is missing: ${script}`);\n  }\n  return { command: process.execPath, args: [script, ...args] };\n}\n","sourceCodeStart":47,"sourceCodeEnd":79,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/portable-command.ts#L47-L79","documentation":"Thrown by portableInvocation() on Windows when a resolved command resolves to a .cmd/.bat shim that is unsafe to execute directly: it is not a regular file or exceeds 256 KiB. Launching .cmd/.bat files via spawn is both a command-injection risk and unreliable for huge auto-generated npm shims, so the library refuses and requires a safe native executable. There is a sibling error for shims whose script is not a Node shim.","triggerScenarios":"platform === 'win32' and resolveWindowsCommand() resolved the command to a *.cmd/*.bat file whose statSync shows !isFile() or size > 256*1024 bytes.","commonSituations":"npm's npx-shim .cmd files left oversized after a broken install, a directory or corrupted file shadowing the command name on PATH, or antivirus quarantine leaving a stub .cmd.","solutions":["Install a native .exe version of the tool (e.g. via npm global with node, or the vendor's Windows installer) instead of relying on the .cmd shim.","Delete and reinstall the package to regenerate a clean, small .cmd shim (`npm install -g <pkg>`).","Ensure the resolved path is a regular file; remove directories/files shadowing the command on PATH.","Call the underlying node script directly: `node <pkg-root>/bin/cli.js ...` instead of the shim."],"exampleFix":"// before (Windows)\nspawn(\"npm.cmd\", [\"run\", \"build\"])   // may throw: shim unsafe (size/file)\n// after\nspawn(\"node\", [require.resolve(\"npm/bin/npm-cli.js\"), \"run\", \"build\"], { windowsHide: true })","handlingStrategy":"validation","validationCode":"import { statSync } from \"fs\";\nfunction isSafeCmdShim(p: string): boolean {\n  if (!/\\.(?:cmd|bat)$/i.test(p)) return true;\n  try { const s = statSync(p); return s.isFile() && s.size <= 256 * 1024; }\n  catch { return false; }\n}\n// call isSafeCmdShim(resolvedExecutable) before spawning","typeGuard":null,"tryCatchPattern":"try {\n  spawn(invocation(cmd, args).command, invocation(cmd, args).args);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"cannot safely launch Windows command shim\")) {\n    console.error(\"Shim unsafe; reinstall the package or use its native .exe/node entry\", e.message);\n  } else throw e;\n}","preventionTips":["Prefer native .exe installs on Windows over .cmd wrappers","Reinstall npm packages whose shims look oversized or corrupted","Keep PATH clean of shadowing files with .cmd/.bat extensions","On Windows, spawn node entry scripts directly instead of .cmd shims"],"tags":["windows","spawn","security","npm"],"backgroundTag":"unsupported-platform","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}