hcengineering/platform · error · Error

"npm ${command}" encountered an error

Error message

"npm ${command}" encountered an error

What it means

Rush's install-run.js shim runs `npm install <name>@<version>` into a temp folder to provision a package tool on demand. If the spawned npm process exits with a non-zero status, this Error is thrown. It means npm itself completed (was found and executed) but the install failed, and the failure message was already streamed via stdio: 'inherit'.

Source

Thrown at foundations/communication/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 printed above the error (stdio is inherited) to find the underlying npm failure.
  2. Verify the package name and version in the install-run invocation exist in the registry (`npm view <name>@<version>`).
  3. Check network/registry access: run `npm config get registry`, and confirm proxy/.npmrc auth is configured.
  4. Clear the cached install folder under common/temp (install-run uses a temp install dir) and retry.
  5. Run the npm install manually in the same environment to reproduce and fix environment issues.

Example fix

// before
node common/scripts/install-run.js qrcode@^1.2.0 qrcode -f x
// Error: "npm install" encountered an error
// after: fix the specifier to a resolvable version
node common/scripts/install-run.js qrcode@1.4.2 qrcode -f x
Defensive patterns

Strategy: try-catch

Validate before calling

const spec = 'qrcode@^1.2.0'
const [name, version] = spec.split('@')
const res = await fetch(`https://registry.npmjs.org/${name}/${version}`)
if (!res.ok) throw new Error(`Package ${spec} not resolvable in registry`)

Try / catch

try {
  await runBootstrap()
} catch (e) {
  if (String(e).includes('encountered an error')) {
    console.error('npm install failed; check npm output above and registry access')
  }
  throw e
}

Prevention

When it happens

Trigger: Running `node install-run.js <pkg>@<version> <bin>` (or install-run-rush.js) when the child `npm install` process exits non-zero — e.g. package/version not found in the registry, network/registry auth failure, or npm configured with a failing pre/post script.

Common situations: Typo in package name or version in a bootstrap script; corporate proxy or private registry blocking the fetch; npm scripts hook failing; out-of-disk space; Node/npm version mismatch producing engine errors.

Related errors

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