{"record":{"id":"23b9cde518a44fdf","repo":"JuliusBrussee/caveman","slug":"windows-command-shim-target-missing-script","errorCode":null,"errorMessage":"Windows command shim target missing: ${script}","messagePattern":"Windows command shim target missing: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/delegate/portable-process.mjs","lineNumber":43,"sourceCode":"  }\n  return null;\n}\n\nexport function portableInvocation(command, args, platform = process.platform, env = process.env) {\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) throw new Error(`unsafe Windows command shim: ${executable}`);\n  let relativeScript = null;\n  for (const line of readFileSync(executable, \"utf8\").split(/\\r?\\n/)) {\n    if (!/(?:\\bnode(?:\\.exe)?\\b|_prog)/i.test(line) || !/%\\*/.test(line)) continue;\n    const match = line.match(/\"%(?:dp0%|~dp0)\\\\([^\"\\r\\n]+\\.(?:cjs|mjs|js))\"\\s+%\\*/i);\n    if (match) { relativeScript = match[1]; break; }\n  }\n  if (!relativeScript) throw new Error(`non-Node Windows command shim: ${executable}`);\n  const script = resolve(dirname(executable), ...relativeScript.split(/[\\\\/]+/));\n  if (!statSync(script).isFile()) throw new Error(`Windows command shim target missing: ${script}`);\n  return { command: process.execPath, args: [script, ...args] };\n}\n\nexport function delegateSpawnOptions(platform = process.platform) {\n  return {\n    detached: platform !== \"win32\",\n    windowsHide: true,\n  };\n}\n\nexport async function killProcessTree(\n  child,\n  platform = process.platform,\n  taskkill = spawnSync,\n  kill = process.kill,\n  graceMs = 1500,\n) {\n  if (!child?.pid) return;","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/agents/delegate/portable-process.mjs#L25-L61","documentation":"portableInvocation() resolved the Node script that a Windows .cmd/.bat shim forwards to, but statSync says that target is not an existing file. The safe-spawn path will not fall back to executing the raw batch file, so it fails fast with the resolved absolute script path in the message.","triggerScenarios":"A stale or half-installed package: the .bin shim exists but the JS entrypoint it points to was deleted, moved, or never extracted; broken %~dp0 resolution after node_modules was relocated.","commonSituations":"Interrupted installs; aggressive node_modules cleaners (npkill, dedupe tools); monorepo hoisting moving the package while leaving the workspace .bin shim; Windows path-length limits truncating extraction.","solutions":["Do a clean reinstall of the package owning the shim (rm -rf node_modules plus a lockfile-exact install)","Check the printed absolute path — if it looks truncated or wrong-shaped, fix PATH length or Long Paths settings and reinstall","Invoke the real entrypoint with node directly, bypassing the shim"],"exampleFix":"# before\n# Windows command shim target missing: C:\\proj\\node_modules\\.bin\\..\\foo\\dist\\cli.js\n\n# after\nnpm ci   # clean, lockfile-exact reinstall restores the target file","handlingStrategy":"fallback","validationCode":"// before spawn: probe the shim's forwarded target\nconst ok = shimTargetExists(cmd); // see error 464 validationCode\nif (!ok) await cleanReinstall(pkg);","typeGuard":null,"tryCatchPattern":"try { spawn(inv.command, inv.args); }\ncatch (e) {\n  if (/shim target (?:is )?missing/.test(String(e?.message))) { await reinstall(pkg); }\n  else throw e;\n}","preventionTips":["Use lockfile-exact installs (npm ci) in CI and locally","Re-run install after any tool prunes node_modules"],"tags":["windows","spawn","npm","filesystem"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}