{"record":{"id":"d8acf46d13a57bca","repo":"JuliusBrussee/caveman","slug":"windows-command-shim-target-is-missing-script-d8acf4","errorCode":null,"errorMessage":"Windows command shim target is missing: ${script}","messagePattern":"Windows command shim target is missing: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/subagent-tax/lib/process-tree.mjs","lineNumber":56,"sourceCode":"export function portableProcessInvocation(\n  command,\n  args,\n  { platform = process.platform, env = process.env, execPath = process.execPath } = {},\n) {\n  if (platform !== \"win32\") return { command, args: [...args] };\n  const executable = resolveWindowsCommand(command, env);\n  if (!executable) throw Object.assign(new Error(`command not found: ${command}`), { code: \"ENOENT\" });\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 relativeScript = parseWindowsNodeShim(readFileSync(executable, \"utf8\"));\n  if (!relativeScript) {\n    throw new Error(`cannot safely launch non-Node Windows command shim: ${executable}`);\n  }\n  const script = resolve(dirname(executable), ...relativeScript.split(/[\\\\/]+/));\n  if (!statSync(script).isFile()) throw new Error(`Windows command shim target is missing: ${script}`);\n  return { command: execPath, args: [script, ...args] };\n}\n\nexport function harnessSpawnOptions(platform = process.platform) {\n  return {\n    detached: platform !== \"win32\",\n    windowsHide: true,\n  };\n}\n\nexport function forceKillTree(\n  child,\n  {\n    platform = process.platform,\n    kill = process.kill,\n    taskkill = spawnSync,\n  } = {},\n) {","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/subagent-tax/lib/process-tree.mjs#L38-L74","documentation":"Thrown by portableProcessInvocation() on win32 when the .cmd/.bat shim parsed as a Node wrapper, but the relative script path it references does not resolve to an existing file. This catches broken installs where the launcher survived but the package payload (the actual .js entry point) is missing — failing before spawn instead of producing a confusing Node MODULE_NOT_FOUND later.","triggerScenarios":"Calling portableProcessInvocation with platform win32 where the shim's %~dp0-relative target (e.g. \"..\\\\node_modules\\\\@scope\\\\pkg\\\\bin.js\") was deleted, moved, or never installed — typically after a partial npm install, a manual node_modules prune, or moving the project directory without reinstalling.","commonSituations":"node_modules copied or synced incompletely; package upgraded and its bin path changed while an old shim remained on PATH; project moved to a different path breaking absolute references inside a generated shim.","solutions":["Check whether the script path named in the error exists; if not, reinstall the owning package (delete node_modules and lockfile-consistent reinstall).","If an old shim on a global PATH points into a relocated/deleted project, remove that stale shim from PATH or delete the stale file.","Verify with `where <command>` that PATH precedence picks the shim inside the current install, not a leftover one elsewhere."],"exampleFix":"# before: stale global shim points at deleted checkout\n# C:\\Users\\me\\AppData\\...\\my-cli.cmd -> ..\\..\\gone-project\\node_modules\\...\\cli.js (missing)\n\n# after\nnpm uninstall -g my-cli && npm install -g my-cli@latest","handlingStrategy":"validation","validationCode":"import { existsSync } from \"node:fs\";\n// before invoking, confirm the shim's target exists (mirror of the resolver):\nfunction shimTargetExists(shimPath) {\n  const m = /node_modules[^\"']*/.exec(readFileSync(shimPath, \"utf8\"));\n  return m ? existsSync(resolve(dirname(shimPath), m[0])) : false;\n}","typeGuard":null,"tryCatchPattern":"try {\n  const inv = portableProcessInvocation(cmd, args, { platform: \"win32\" });\n} catch (err) {\n  if (/shim target is missing/.test(err.message)) {\n    // prompt reinstall of the owning package, then retry once\n  } else throw err;\n}","preventionTips":["Run a clean reinstall after moving a project or pruning node_modules.","Periodically remove stale global shims (`where -all <cmd>` to find them)."],"tags":["windows","spawn","cmd-shim","broken-install"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}