hcengineering/platform · error

Invalid package specifier: ${rawPackageSpecifier}

Error message

Invalid package specifier: ${rawPackageSpecifier}

What it means

_parsePackageSpecifier splits a raw specifier like "name@version" (or "@scope/name@version") into package name and version. If the computed name part is empty, the specifier is malformed and the script throws this error.

Source

Thrown at foundations/server/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 a well-formed specifier: <name>[@<version>], e.g. "pnpm@7.28.0" or "@scope/pkg@1.0.0"
  2. Check the RUSH_PKG_NAME/RUSH_PKG_VERSION or hardcoded constants in install-run-rush*.js wrappers are non-empty
  3. Quote arguments in shell scripts so variables do not expand to empty and get dropped

Example fix

// before
runInstallRunInPackage('');
runInstallRunInPackage('@1.2.3');
// after
runInstallRunInPackage('typescript@5.4.5');
runInstallRunInPackage('@rushstack/heft@0.60.0');
Defensive patterns

Strategy: validation

Validate before calling

function isValidSpecifier(s) {
  return typeof s === 'string' && s.length > 0 && /^(@[a-z0-9-~][a-z0-9-._~]*\/)?.[a-zA-Z0-9-._~]+(@[0-9a-zA-Z.+\-~]+)?$/.test(s);
}
if (!isValidSpecifier(raw)) throw new Error(`Bad specifier: ${raw}`);

Type guard

function isPackageSpecifier(v) {
  return typeof v === 'string' && v.trim().length > 0 && !v.startsWith('@ver') && v.split('@').filter(Boolean).length >= 1;
}

Try / catch

try {
  runInstallRunInPackage(spec);
} catch (e) {
  if (String(e).startsWith('Invalid package specifier')) {
    console.error(`Use <name>[@<version>] form, e.g. pnpm@8.15.4; got: ${spec}`);
  } else throw e;
}

Prevention

When it happens

Trigger: Passing a specifier that starts with the separator (e.g. "@version", ".5.0"); an empty string; a specifier like "@scope/" where the name resolves to empty; callers of the runUnmanaged/install-run scripts supplying a bad package argument.

Common situations: Typo in install-run-rushp/rushx wrappers' hardcoded package specifiers after edits; shell variable expansion yielding an empty package name in custom scripts; hand-written invocations like install-run.js "@1.2.3".

Related errors

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