hcengineering/platform · error

"npm ${command}" encountered an error

Error message

"npm ${command}" encountered an error

What it means

_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.

Source

Thrown at foundations/server/common/scripts/install-run.js:644

        throw new Error(`Unable to create package.json: ${e}`);
    }
}
/**
 * Run "npm install" in the package install folder.
 */
function _installPackage(logger, packageInstallFolder, name, version, command) {
    try {
        logger.info(`Installing ${name}...`);
        const npmPath = getNpmPath();
        const platformNpmPath = _getPlatformPath(npmPath);
        const result = child_process__WEBPACK_IMPORTED_MODULE_0__.spawnSync(platformNpmPath, [command], {
            stdio: 'inherit',
            cwd: packageInstallFolder,
            env: process.env,
            shell: _isWindows()
        });
        if (result.status !== 0) {
            throw new Error(`"npm ${command}" encountered an error`);
        }
        logger.info(`Successfully installed ${name}@${version}`);
    }
    catch (e) {
        throw new Error(`Unable to install package: ${e}`);
    }
}
/**
 * Get the ".bin" path for the package.
 */
function _getBinPath(packageInstallFolder, binName) {
    const binFolderPath = path__WEBPACK_IMPORTED_MODULE_3__.resolve(packageInstallFolder, NODE_MODULES_FOLDER_NAME, '.bin');
    const resolvedBinName = _isWindows() ? `${binName}.cmd` : binName;
    return path__WEBPACK_IMPORTED_MODULE_3__.resolve(binFolderPath, resolvedBinName);
}
/**
 * Returns a cross-platform path - windows must enclose any path containing spaces within double quotes.
 */

View on GitHub (pinned to 63e28dc964)

Solutions

  1. Read the npm output above the error for the actual failure (registry 404, EACCES, network, etc.) and fix that root cause
  2. Verify the package name/version passed to install-run exist on the registry (npm view <pkg>@<version>)
  3. If using a lockfile (npm ci), ensure it matches the requested dependency; otherwise drop the lockfile path so npm install is used
  4. Check registry connectivity/proxy config (npm config get registry, HTTPS_PROXY) and retry
  5. Clear the npm cache (npm cache clean --force) if corrupted-cache errors appear

Example fix

// before
node common/scripts/install-run.js @mystack/nonexistent-pkg ^1.0.0 pkg
// after (verify the package/version first)
npm view @mystack/real-pkg versions && node common/scripts/install-run.js @mystack/real-pkg ^1.0.0 pkg
Defensive patterns

Strategy: retry

Validate before calling

const { execSync } = require('child_process')
execSync('npm -v', { stdio: 'ignore' }) // throws early if npm is unusable
// optionally: execSync(`npm view ${name}@${version} version`, { stdio: 'ignore' }) to verify the package resolves

Try / catch

try {
  installAndRun(logger, pkg, version, bin, args)
} catch (e) {
  if (e.message.includes('encountered an error')) {
    // npm output with the real cause was printed above; retry once after cleanup
    fs.rmSync('common/temp/install-run', { recursive: true, force: true })
    installAndRun(logger, pkg, version, bin, args)
  } else throw e
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/20f6c2732f1d881d. Report an issue: GitHub.