{"record":{"id":"20f6c2732f1d881d","repo":"hcengineering/platform","slug":"npm-command-encountered-an-error-20f6c2","errorCode":null,"errorMessage":"\"npm ${command}\" encountered an error","messagePattern":"\"npm (.+?)\" encountered an error","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"foundations/server/common/scripts/install-run.js","lineNumber":644,"sourceCode":"        throw new Error(`Unable to create package.json: ${e}`);\n    }\n}\n/**\n * Run \"npm install\" in the package install folder.\n */\nfunction _installPackage(logger, packageInstallFolder, name, version, command) {\n    try {\n        logger.info(`Installing ${name}...`);\n        const npmPath = getNpmPath();\n        const platformNpmPath = _getPlatformPath(npmPath);\n        const result = child_process__WEBPACK_IMPORTED_MODULE_0__.spawnSync(platformNpmPath, [command], {\n            stdio: 'inherit',\n            cwd: packageInstallFolder,\n            env: process.env,\n            shell: _isWindows()\n        });\n        if (result.status !== 0) {\n            throw new Error(`\"npm ${command}\" encountered an error`);\n        }\n        logger.info(`Successfully installed ${name}@${version}`);\n    }\n    catch (e) {\n        throw new Error(`Unable to install package: ${e}`);\n    }\n}\n/**\n * Get the \".bin\" path for the package.\n */\nfunction _getBinPath(packageInstallFolder, binName) {\n    const binFolderPath = path__WEBPACK_IMPORTED_MODULE_3__.resolve(packageInstallFolder, NODE_MODULES_FOLDER_NAME, '.bin');\n    const resolvedBinName = _isWindows() ? `${binName}.cmd` : binName;\n    return path__WEBPACK_IMPORTED_MODULE_3__.resolve(binFolderPath, resolvedBinName);\n}\n/**\n * Returns a cross-platform path - windows must enclose any path containing spaces within double quotes.\n */","sourceCodeStart":626,"sourceCodeEnd":662,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/server/common/scripts/install-run.js#L626-L662","documentation":"_installPackage spawns `npm install`/`npm ci` (or a pnpm/yarn variant) in the temporary package folder with stdio inherit. If the child process exits with a non-zero status, the script throws this generic error. The real npm error output is printed above the exception because stdio is inherited, so read the npm log lines preceding the stack trace for the root cause.","triggerScenarios":"npm install/ci exits non-zero: registry unreachable, package name/version not resolvable, lockfile mismatch with package.json, npm network/proxy problems, or unsupported npm flags.","commonSituations":"Corporate proxy/firewall blocking registry.npmjs.org; typo in package name or an invalid semver range; npm ci run with a package-lock.json that doesn't match the generated package.json; offline CI without an npm cache.","solutions":["Read the npm output above the error for the actual failure (registry 404, EACCES, network, etc.) and fix that root cause","Verify the package name/version passed to install-run exist on the registry (npm view <pkg>@<version>)","If using a lockfile (npm ci), ensure it matches the requested dependency; otherwise drop the lockfile path so npm install is used","Check registry connectivity/proxy config (npm config get registry, HTTPS_PROXY) and retry","Clear the npm cache (npm cache clean --force) if corrupted-cache errors appear"],"exampleFix":"// before\nnode common/scripts/install-run.js @mystack/nonexistent-pkg ^1.0.0 pkg\n// after (verify the package/version first)\nnpm view @mystack/real-pkg versions && node common/scripts/install-run.js @mystack/real-pkg ^1.0.0 pkg","handlingStrategy":"retry","validationCode":"const { execSync } = require('child_process')\nexecSync('npm -v', { stdio: 'ignore' }) // throws early if npm is unusable\n// optionally: execSync(`npm view ${name}@${version} version`, { stdio: 'ignore' }) to verify the package resolves","typeGuard":null,"tryCatchPattern":"try {\n  installAndRun(logger, pkg, version, bin, args)\n} catch (e) {\n  if (e.message.includes('encountered an error')) {\n    // npm output with the real cause was printed above; retry once after cleanup\n    fs.rmSync('common/temp/install-run', { recursive: true, force: true })\n    installAndRun(logger, pkg, version, bin, args)\n  } else throw e\n}","preventionTips":["Check registry connectivity/proxy settings before CI install steps","Validate package name/version with npm view before invoking","Keep npm/Node versions current and consistent"],"tags":["npm","rush","network","child-process"],"backgroundTag":"npm-install-failed","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}