Unable to determine the required version of Rush from ${RUSH

Error message

Unable to determine the required version of Rush from ${RUSH_JSON_FILENAME} (${rushJsonFolder}). The 'rushVersion' field is either not assigned in ${RUSH_JSON_FILENAME} or was specified using an unexpected syntax.

What it means

install-run-rush.js bootstraps the correct Rush version by reading rush.json with a regex that expects a quoted "rushVersion": "x.y.z" field. If rush.json is missing the field, malformed, or uses syntax the regex can't match, it throws this generic Error instead of returning a version.

Source

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

const RUSH_PREVIEW_VERSION = 'RUSH_PREVIEW_VERSION';
const INSTALL_RUN_RUSH_LOCKFILE_PATH_VARIABLE = 'INSTALL_RUN_RUSH_LOCKFILE_PATH';
function _getRushVersion(logger) {
    const rushPreviewVersion = process.env[RUSH_PREVIEW_VERSION];
    if (rushPreviewVersion !== undefined) {
        logger.info(`Using Rush version from environment variable ${RUSH_PREVIEW_VERSION}=${rushPreviewVersion}`);
        return rushPreviewVersion;
    }
    const rushJsonFolder = findRushJsonFolder();
    const rushJsonPath = path__WEBPACK_IMPORTED_MODULE_0__.join(rushJsonFolder, RUSH_JSON_FILENAME);
    try {
        const rushJsonContents = fs__WEBPACK_IMPORTED_MODULE_1__.readFileSync(rushJsonPath, 'utf-8');
        // Use a regular expression to parse out the rushVersion value because rush.json supports comments,
        // but JSON.parse does not and we don't want to pull in more dependencies than we need to in this script.
        const rushJsonMatches = rushJsonContents.match(/\"rushVersion\"\s*\:\s*\"([0-9a-zA-Z.+\-]+)\"/);
        return rushJsonMatches[1];
    }
    catch (e) {
        throw new Error(`Unable to determine the required version of Rush from ${RUSH_JSON_FILENAME} (${rushJsonFolder}). ` +
            `The 'rushVersion' field is either not assigned in ${RUSH_JSON_FILENAME} or was specified ` +
            'using an unexpected syntax.');
    }
}
function _getBin(scriptName) {
    switch (scriptName.toLowerCase()) {
        case 'install-run-rush-pnpm.js':
            return 'rush-pnpm';
        case 'install-run-rushx.js':
            return 'rushx';
        default:
            return 'rush';
    }
}
function _run() {
    const [nodePath /* Ex: /bin/node */, scriptPath /* /repo/common/scripts/install-run-rush.js */, ...packageBinArgs /* [build, --to, myproject] */] = process.argv;
    // Detect if this script was directly invoked, or if the install-run-rushx script was invokved to select the
    // appropriate binary inside the rush package to run

View on GitHub (pinned to 63e28dc964)

Solutions

Open rush.json and ensure it contains a properly quoted "rushVersion": "5.x.x" field (double quotes, no comments inside the value).
Validate rush.json is valid JSON and readable at the expected rushJsonFolder location.
Restore rushVersion from a known-good template or re-run the Rush upstream sync to regenerate rush.json.
If the version needs a range or non-standard syntax, run rush directly via a globally installed @microsoft/rush instead of this bootstrap script.

Example fix

// before (rush.json)
{
  // "rushVersion": "5.62.0"
}
// after
{
  "rushVersion": "5.62.0"
}

Defensive patterns

Strategy: validation

Validate before calling

const rushJson = JSON.parse(fs.readFileSync('rush.json', 'utf8').replace(/\/\/.*$/gm, ''))
if (!/^\d+\.\d+\.\d+(-[0-9a-zA-Z.]+)?$/.test(rushJson.rushVersion ?? '')) {
  throw new Error('rush.json rushVersion missing or malformed')
}

Type guard

function hasValidRushVersion(json: unknown): json is { rushVersion: string } {
  return typeof (json as any)?.rushVersion === 'string' &&
    /^\d+\.\d+\.\d+/.test((json as any).rushVersion)
}

Prevention

Always edit rush.json with the rush CLI (rush update / rush version bump) instead of by hand.
Keep rushVersion in semver x.y.z form with double quotes; never comment out the field.
Add a repo lint rule/CI check that parses rush.json and asserts rushVersion matches /\d+\.\d+\.\d+/.
After rebase/merge, diff rush.json to catch dropped or mangled rushVersion fields.

When it happens

Trigger: Running install-run-rush.js (e.g. via the rush bootstrap script) where the repo's rush.json either lacks rushVersion, has it commented out, uses single quotes/unquoted values, or the file itself could not be read/parsed.

Common situations: A freshly scaffolded repo where rush.json was hand-edited; upgrading Rush left an invalid or commented-out rushVersion; a JSON5-style config the strict regex cannot parse; rush.json located in the wrong folder passed as rushJsonFolder.

Related errors

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