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 parses rush.json with a regex to find the "rushVersion" field (avoiding extra dependencies since rush.json allows comments). If the regex finds no match, rushJsonMatches is null and accessing [1] throws inside the catch, producing this error. It means Rush could not determine which version of itself to install.

Source

Thrown at foundations/server/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 a properly quoted field exists: "rushVersion": "5.x.x"
Ensure the value contains only digits, letters, dots, plus and hyphen (valid semver, no spaces)
Validate rush.json parses (comments allowed) and that the script found the correct repo root rush.json
Commit a known-good rush.json from the Rush template if the file is corrupted

Example fix

// before
{
  // "rushVersion": ,
  "npmVersion": "6.14.0"
}
// after
{
  "rushVersion": "5.102.0",
  "npmVersion": "6.14.0"
}

Defensive patterns

Strategy: validation

Validate before calling

const contents = fs.readFileSync('rush.json', 'utf8');
const m = contents.match(/"rushVersion"\s*:\s*"([0-9a-zA-Z.+\-]+)"/);
if (!m) throw new Error('rush.json is missing a valid quoted "rushVersion" field');

Type guard

function hasRushVersion(contents) {
  return /"rushVersion"\s*:\s*"[0-9a-zA-Z.+\-]+"/.test(contents);
}

Try / catch

try {
  runRushScript();
} catch (e) {
  if (String(e).includes("Unable to determine the required version of Rush")) {
    console.error('Fix rush.json: add "rushVersion": "<semver>"');
  } else throw e;
}

Prevention

Never hand-edit rushVersion; use `rush update` or the Rush upgrade tool
Keep rush.json committed and validate it in CI before running bootstrap scripts
Use only plain double-quoted semver values in rush.json

When it happens

Trigger: rush.json is missing the "rushVersion" field entirely; the field uses single quotes, no quotes, or a value with characters outside [0-9a-zA-Z.+-]; rush.json is malformed so reading it throws; the wrong rush.json file was located.

Common situations: Hand-edited rush.json where the version was removed or reformatted; tools rewriting rush.json with non-standard JSON syntax; repo bootstrap scripts run before rush.json is committed; typos like rushVerion.

Related errors

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