{"id":"c12f91ba58616ccd","repo":"gohugoio/hugo","slug":"binary-q-is-not-a-node-js-script","errorCode":null,"errorMessage":"binary %q is not a Node.js script","messagePattern":"binary %q is not a Node\\.js script","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/hexec/exec.go","lineNumber":217,"sourceCode":"\t\t\tresolvedBin = p\n\t\t\tloc = binaryLocationNodeModules\n\t\t} else if p, err := exec.LookPath(name); err == nil {\n\t\t\tresolvedBin = p\n\t\t\tloc = binaryLocationPath\n\t\t} else {\n\t\t\treturn nil, &NotFoundError{name: name, method: \"in PATH\"}\n\t\t}\n\n\t\tscriptPath := resolveNodeBin(resolvedBin)\n\n\t\te.infol.WithFields(logg.Fields{\n\t\t\tlogg.Field{Name: \"location\", Value: loc},\n\t\t\tlogg.Field{Name: \"bin\", Value: resolvedBin},\n\t\t\tlogg.Field{Name: \"script\", Value: scriptPath},\n\t\t}).Logf(\"resolve %q\", name)\n\n\t\tif scriptPath == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"binary %q is not a Node.js script\", name)\n\t\t}\n\n\t\treturn func(arg2 ...any) (Runner, error) {\n\t\t\treturn e.newNode(name, scriptPath, arg2...)\n\t\t}, nil\n\t})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn newRunner(arg...)\n}\n\n// newNode runs a Node.js script via \"node [--permission <flags>] <scriptPath> <args>\".\nfunc (e *Exec) newNode(name, scriptPath string, arg ...any) (Runner, error) {\n\tvar allArgs []any\n\tfor _, pa := range e.nodePermissionArgs(name, scriptPath) {\n\t\tallArgs = append(allArgs, pa)","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/common/hexec/exec.go#L199-L235","documentation":"Returned in common/hexec/exec.go:217 when Hugo resolves a command expected to be a Node.js tool (e.g. from node_modules/.bin or PATH) but resolveNodeBin cannot extract an underlying JavaScript entry script from the resolved binary. Hugo runs such tools as 'node <script> <args>' (optionally with Node permission flags), so a resolved file that isn't a Node wrapper/script cannot be executed through this path.","triggerScenarios":"Executing a Node-routed external command (such as PostCSS, TailwindCSS, or Babel via css.PostCSS / js build pipelines) where the file found in node_modules/.bin or PATH is not a recognizable Node.js launcher script — e.g. a native binary, a shell wrapper Hugo can't parse, or a broken symlink target.","commonSituations":"npm/pnpm/yarn installs that create non-standard .bin shims (pnpm shell shims on some platforms), a same-named native binary shadowing the Node tool on PATH, corrupted or partially installed node_modules, or Windows .cmd/.ps1 shim variations Hugo's resolver doesn't map to a script.","solutions":["Reinstall the tool so a standard Node bin shim exists: delete node_modules and run 'npm install' (or your package manager's equivalent) in the project root.","Verify what Hugo resolved: check node_modules/.bin/<name> and confirm it points at a .js entry (head the file / readlink).","Ensure a native binary of the same name earlier in PATH isn't shadowing the Node package's executable.","Try installing the tool with npm instead of pnpm/yarn if exotic shims are the cause."],"exampleFix":"# before: broken/foreign shim in node_modules/.bin\nrm -rf node_modules\n\n# after: clean install restores standard Node shims\nnpm install\nhugo","handlingStrategy":"validation","validationCode":"# Verify the binary on PATH is actually a Node script (e.g. postcss, babel)\nhead -1 \"$(command -v postcss)\" | grep -q 'node' || echo 'postcss is not a Node.js script'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install JS tooling (postcss-cli, babel) locally via npm so Hugo resolves the Node script in node_modules/.bin, not a native binary with the same name","Avoid shadowing tool names with unrelated native executables earlier on PATH","After changing PATH or reinstalling tools, run a clean build to confirm resolution"],"tags":["hugo","nodejs","external-tools","postcss","environment"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}