hcengineering/platform · error · Error

Invalid package specifier: ${rawPackageSpecifier}

Error message

Invalid package specifier: ${rawPackageSpecifier}

What it means

_parsePackageSpecifier splits a raw "name[@version]" string into { name, version }. It throws this error when the resulting package name is empty, meaning the specifier had no usable name portion (e.g. it was empty, or only "@version"). The script uses this in install-and-run mode to install and invoke a package's binary without a full checkout.

Source

Thrown at foundations/communication/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 valid package specifier: the first argument must be the package name, e.g. "pnpm@8.15.4" or "name@version".
  2. Check the shell variable feeding the specifier for emptiness before invoking the script.
  3. For scoped packages use the correct form "@scope/name@version"; do not strip the scope.
  4. Escape the @ in the shell if needed (some shells interpolate) so the name portion survives.

Example fix

// before
node install-run.js $EMPTY_VAR@1.0.0
// after
node install-run.js "${PACKAGE_NAME:?PACKAGE_NAME must be set}@${PACKAGE_VERSION:-latest}"
Defensive patterns

Strategy: validation

Validate before calling

const spec = process.argv[2] || '';
if (!spec || !/^[^@:]+/.test(spec.replace(/^@/, '@scope-ok'))) throw new Error('usage: install-run.js <name[@version]> [-- args]');

Try / catch

try { runInstall(); } catch (e) { if (/Invalid package specifier/.test(e.message)) { console.error('Bad package specifier:', process.argv[2]); process.exit(2); } throw e; }

Prevention

When it happens

Trigger: Calling the install-run script with a package specifier argument that is empty, contains only a version (e.g. ":1.2.3" separator form producing an empty name), or is otherwise malformed so the parsed name is a falsy string.

Common situations: CI pipeline variables like PACKAGE_SPEC being unset or empty and interpolated into the command line; typos such as "@scoped-pkg@1.2.3" missing the actual package name; passing a leading separator by mistake.

Related errors

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