hcengineering/platform · error

Invalid package specifier: ${rawPackageSpecifier}

Error message

Invalid package specifier: ${rawPackageSpecifier}

What it means

_parsePackageSpecifier splits a raw specifier like 'name@version' into { name, version }. If the resulting name portion is empty — e.g. the specifier starts with '@' or '@' with no name before a separator — it throws 'Invalid package specifier: <raw>'.

Source

Thrown at foundations/utils/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 full specifier including the package name: 'lodash@4.17.21' or '@scope/pkg@1.0.0'
  2. Check shell quoting so the '@' segment isn't split or lost
  3. Validate the specifier in the calling script before invoking install-run.js

Example fix

// before
node install-run.js run @1.2.3
// after
node install-run.js run my-package@1.2.3
Defensive patterns

Strategy: validation

Validate before calling

function assertPackageSpecifier(raw) {
  if (typeof raw !== 'string' || raw.length === 0) {
    throw new Error(`package specifier required, got: ${JSON.stringify(raw)}`)
  }
  const idx = raw.indexOf('@', raw[0] === '@' ? 1 : 0)
  const name = idx > 0 ? raw.substring(0, idx) : (raw[0] === '@' ? raw : raw.split('@')[0])
  if (!name) throw new Error(`invalid package specifier: ${raw}`)
}

Type guard

function isValidPackageSpecifier(raw) {
  return typeof raw === 'string' &&
    (/^@[^@/]+\/[^@]+(@.+)?$/.test(raw) || /^[^@]+(@.+)?$/.test(raw))
}

Try / catch

try {
  runPackage(specifier, ...)
} catch (e) {
  if (String(e.message).startsWith('Invalid package specifier:')) {
    console.error(`'${specifier}' must be 'name[@version]' or '@scope/name[@version]'`)
    process.exit(1)
  }
  throw e
}

Prevention

When it happens

Trigger: Calling install-run.js / runPackage with a package specifier that has no name portion: '@1.2.3', '@scope/', or an empty string after parsing the '@' separator.

Common situations: Hand-typed CLI argument with a leading '@' and missing package name; shell quoting dropping part of the argument; script variable interpolating to '@version'.

Related errors

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