Unable to determine the required version of Rush from rush.j

Error message

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

What it means

install-run-rush.js reads rush.json and extracts the rushVersion field with a regex (because rush.json allows comments). If reading/parsing fails or the regex doesn't match — rushVersion missing, empty, or in an unexpected syntax — _getRushVersion throws this descriptive error.

Source

Thrown at foundations/utils/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 set "rushVersion" to a valid version string, e.g. "rushVersion": "5.100.0"
Validate rush.json is readable, valid JSON-with-comments, and the version matches [0-9a-zA-Z.+-]+
Restore rush.json from the repo template if it was corrupted

Example fix

// before (rush.json)
{
  // no rushVersion
  "repository": {...}
}
// after (rush.json)
{
  "rushVersion": "5.100.0",
  "repository": {...}
}

Defensive patterns

Strategy: try-catch

Validate before calling

const fs = require('fs')
function assertRushVersion(rushJsonFolder) {
  const contents = fs.readFileSync(`${rushJsonFolder}/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 rushVersion string')
}

Type guard

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

Try / catch

try {
  require('./common/scripts/install-run-rush.js')
} catch (e) {
  if (String(e.message).includes("Unable to determine the required version of Rush")) {
    console.error('Fix rush.json: add "rushVersion": "x.y.z" (valid chars: [0-9a-zA-Z.+-])')
    process.exit(1)
  }
  throw e
}

Prevention

Never remove rushVersion when hand-editing rush.json; keep it at the top with a comment
Add a repo lint/CI check asserting rushVersion matches the expected regex
Regenerate rush.json from the rush template rather than editing from scratch

When it happens

Trigger: Running install-run-rush.js (e.g. via a rush bootstrap script) in a repo whose rush.json lacks a valid "rushVersion": "x.y.z" string, or where the file cannot be read.

Common situations: Freshly scaffolded repo where rush.json was hand-edited and rushVersion removed; malformed JSON; rushVersion written with a syntax the regex doesn't accept (e.g. non-sem chars).

Related errors

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