Egonex-AI/Understand-Anything · error

Usage: node prepare-symbol-retry.mjs <projectRoot>

Error message

Usage: node prepare-symbol-retry.mjs <projectRoot>

What it means

prepare-symbol-retry.mjs is a CLI script that prepares a targeted symbol-level retry for a failed incremental update. main() requires exactly one argument (the project root) and throws this usage error when process.argv.length !== 3, i.e. the wrong number of CLI arguments was supplied.

Source

Thrown at understand-anything-plugin/skills/understand/prepare-symbol-retry.mjs:18

#!/usr/bin/env node
/** Prepare exactly one targeted analyzer retry after the symbol gate fails. */
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { existsSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import {
  atomicWriteJson,
  getIntermediateDir,
  loadSymbolContext,
  normalizePath,
  readJson,
  symbolKind,
  validateIncrementalSymbols,
} from './validate-incremental-symbols.mjs';

async function main() {
  if (process.argv.length !== 3) throw new Error('Usage: node prepare-symbol-retry.mjs <projectRoot>');
  const projectRoot = realpathSync(process.argv[2]);
  const intermediateDir = await getIntermediateDir(projectRoot);
  const { plan, baseline } = loadSymbolContext(projectRoot, intermediateDir);
  if (!['PARTIAL_UPDATE', 'ARCHITECTURE_UPDATE'].includes(plan.action)) {
    throw new Error('Symbol retry requires a partial or architecture incremental update');
  }
  const retryPath = join(intermediateDir, 'incremental-symbol-retry.json');
  if (existsSync(retryPath)) {
    const retry = readJson(retryPath);
    if (retry.baseCommit === plan.baseCommit && retry.headCommit === plan.headCommit && retry.attempt === 1) {
      throw new Error('Symbol retry already used for these commits; stop without advancing the baseline');
    }
  }
  // Do not trust an old report or a caller-supplied list of files to replace.
  const report = await validateIncrementalSymbols(projectRoot, { intermediateDir });
  if (report.ok || report.unresolvedFiles.length === 0) {
    throw new Error('No unresolved symbol files eligible for a targeted retry; inspect the symbol report');
  }

View on GitHub (pinned to 07edf82a04)

Solutions

  1. Invoke with exactly one argument: node prepare-symbol-retry.mjs <projectRoot>.
  2. When passing args through npm/pnpm scripts, use the -- separator: pnpm prepare-symbol-retry -- .
  3. Ensure the project root is a valid path — it is passed through realpathSync next, so use an absolute or correct relative path.

Example fix

// before
node prepare-symbol-retry.mjs
// Error: Usage: node prepare-symbol-retry.mjs <projectRoot>
// after
node prepare-symbol-retry.mjs /path/to/project
Defensive patterns

Strategy: validation

Validate before calling

if (process.argv.length !== 3) {
  console.error('Usage: node prepare-symbol-retry.mjs <projectRoot>');
  process.exit(2);
}

Try / catch

try {
  await runRetry(projectRoot);
} catch (e) {
  if (e.message.startsWith('Usage: node prepare-symbol-retry.mjs')) {
    console.error(e.message);
    process.exitCode = 2;
  } else throw e;
}

Prevention

When it happens

Trigger: Running the script with zero arguments, with more than one argument, or via a wrapper that injects unexpected extra argv entries (e.g. node prepare-symbol-retry.mjs or node prepare-symbol-retry.mjs . --flag).

Common situations: Typo in invocation from a runbook; passing flags the script doesn't support; calling from npm scripts where extra args need a `--` separator; forgetting the project root argument entirely.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/8268f8990089d7cb. Report an issue: GitHub.