hcengineering/platform · error

Invalid package specifier: ${rawPackageSpecifier}

Error message

Invalid package specifier: ${rawPackageSpecifier}

What it means

_parsePackageSpecifier splits a raw package specifier on the last '@' or ':' separator into a name and version. If the resulting name is empty (specifier starts with a separator, e.g. '@1.2.3' or ':1.2.3'), it throws this error because there is no package name to install.

Source

Thrown at foundations/net/common/scripts/install-run.js:366

function _parsePackageSpecifier(rawPackageSpecifier) {
    rawPackageSpecifier = (rawPackageSpecifier || '').trim();
    const separatorIndex = rawPackageSpecifier.lastIndexOf('@');
    let name;
    let version = undefined;
    if (separatorIndex === 0) {
        // The specifier starts with a scope and doesn't have a version specified
        name = rawPackageSpecifier;
    }
    else if (separatorIndex === -1) {
        // The specifier doesn't have a version
        name = rawPackageSpecifier;
    }
    else {
        name = rawPackageSpecifier.substring(0, separatorIndex);
        version = rawPackageSpecifier.substring(separatorIndex + 1);
    }
    if (!name) {
        throw new Error(`Invalid package specifier: ${rawPackageSpecifier}`);
    }
    return { name, version };
}
let _npmPath = undefined;
/**
 * Get the absolute path to the npm executable
 */
function getNpmPath() {
    if (!_npmPath) {
        try {
            if (_isWindows()) {
                // We're on Windows
                const whereOutput = child_process__WEBPACK_IMPORTED_MODULE_0__.execSync('where npm', { stdio: [] }).toString();
                const lines = whereOutput.split(os__WEBPACK_IMPORTED_MODULE_2__.EOL).filter((line) => !!line);
                // take the last result, we are looking for a .cmd command
                // see https://github.com/microsoft/rushstack/issues/759
                _npmPath = lines[lines.length - 1];
            }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Pass the full specifier including the name: node install-run.js <name>[@<version>], e.g. 'typescript@4.9.5'.
2. Quote scoped packages in the shell so the '@' isn't consumed: 'typescript@^4' not @^4.
3. Check the calling npm script / documentation for a missing package name argument.
4. If constructing the specifier programmatically, validate it matches /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@.*)?$/ before invoking.

Example fix

// before
node install-run.js @1.2.3           // invalid: name empty
// after
node install-run.js my-package@1.2.3 // valid: name + version

const SPEC = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@.*)?$/
if (!SPEC.test(rawSpecifier) || rawSpecifier.startsWith('@1') || rawSpecifier.startsWith(':')) {
  throw new Error(`Specifier must be <name>[@<version>], got: ${rawSpecifier}`)
}

function isValidPackageSpecifier(s: string): boolean {
  const [name] = s.split(/[@:]/).filter(Boolean)
  return typeof name === 'string' && name.length > 0
}

When it happens

Trigger: Calling the install-run script (or resolvePackageSpecifier) with an argument like '@1.2.3', ':latest', or an empty/blank name portion before the version separator.

Common situations: Typo in an npm script where the package name was dropped; shell quoting stripped the leading scope name (e.g. '@scope/pkg@1.0.0' mangled by the shell); copy-pasting a version-only string into a bootstrap argument.

Related errors

• Invalid package specifier: ${rawPackageSpecifier}
• Invalid package specifier: ${rawPackageSpecifier}
• Unable to determine the path to the NPM tool: ${e}
• The NPM executable does not exist
• "npm view" returned error code ${npmVersionSpawnResult.statu

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