Egonex-AI/Understand-Anything · error · BenchmarkStageError

Benchmark stage failed: ${stage.name}

Error message

Benchmark stage failed: ${stage.name}

What it means

BenchmarkStageError thrown for the scan stage. After the scan worker runs, the harness reads scanPath (scan.json), calls validateScanArtifact, and on a thrown error marks the stage failed via markArtifactFailure (redacting the message) and summarizes it. If scanStage.status is still 'failed' after that, this BenchmarkStageError is thrown, halting the pipeline before the import stage which depends on scan output.

Source

Thrown at scripts/lib/large-repo-benchmark.mjs:1755

    stageResults.push(scanStage);
    report.stages.scan = summarizeStage(
      scanStage,
      fileSizeOrZero(scanPath),
    );
    let scan = null;
    if (scanStage.status === 'ok') {
      try {
        scan = readJson(scanPath);
        validateScanArtifact(scan);
      } catch (error) {
        markArtifactFailure(scanStage, 'scan', error, redactionRoots);
        report.stages.scan = summarizeStage(
          scanStage,
          fileSizeOrZero(scanPath),
        );
      }
    }
    if (scanStage.status === 'failed') throw new BenchmarkStageError(scanStage);
    report.scale = subjectScale(options.repoRoot, scan);
    report.stages.scan = summarizeStage(scanStage, fileSizeOrZero(scanPath), {
      files: scan.totalFiles,
      lines: report.scale.lines,
      bytes: report.scale.bytes,
      filteredByUserIgnore: scan.filteredByIgnore ?? 0,
    });

    const importInputPath = join(artifactRoot, 'import-input.json');
    const importOutputPath = join(artifactRoot, 'import-map.json');
    writeJson(importInputPath, {
      projectRoot: options.repoRoot,
      files: scan.files,
    });
    onProgress('imports');
    const importStage = await runStage(
      'imports',
      IMPORT_SCRIPT,

View on GitHub (pinned to 32944829e7)

Solutions

1. Read report.stages.scan.stderr — it carries the sanitized original error from markArtifactFailure.
2. Run the scan worker standalone against repoRoot and inspect stderr: node understand-anything-plugin/skills/understand/scan-project.mjs <input.json> <out.json>.
3. Confirm repoRoot exists, is a directory, and is readable by the benchmark process.
4. If the worker is an older version, rebuild/re-sync the plugin so its scan-project.mjs emits the current required schema.
5. For very large repos, raise the worker memory budget so scan-project.mjs is not OOM-killed mid-stream.

Example fix

// before — repoRoot unreadable or wrong type
runBenchmark({ repoRoot: './some-file', outputPath: './b.json' })

// after — verify it is a readable directory first
import { statSync } from 'node:fs';
if (!statSync(opts.repoRoot).isDirectory()) throw new Error('repoRoot must be a directory');
runBenchmark({ repoRoot: opts.repoRoot, outputPath: './b.json' })

import { statSync } from 'node:fs';
function ensureScanInputs(repoRoot) {
  if (!repoRoot) throw new Error('repoRoot required');
  const st = statSync(repoRoot);
  if (!st.isDirectory()) throw new Error('repoRoot must be a directory');
}

try {
  await runBenchmark(options);
} catch (e) {
  if (e instanceof BenchmarkStageError && e.stage.name === 'scan') {
    console.error('scan stage failed:', e.stage.stderr);
    // re-run scan-project.mjs standalone for a fuller error
  } else throw e;
}

When it happens

Trigger: The scan worker exited non-zero or scan.json is missing/invalid JSON, OR validateScanArtifact threw (e.g. totalFiles missing, schema mismatch), causing markArtifactFailure to set scanStage.status='failed'. The subsequent `if (scanStage.status === 'failed') throw new BenchmarkStageError(scanStage)` then aborts.

Common situations: repoRoot points at a path with no scannable files, or to a path the worker cannot read (permission denied). An outdated scan-project.mjs that omits a required field (totalFiles, filteredByIgnore). The worker process was killed (OOM on a huge repo). repoRoot is a file rather than a directory.

Related errors

• Scan artifact does not match the required shape
• Import artifact does not match the required shape
• Batch artifact does not match the required shape
• Invalid knowledge graph: ${result.fatal ?? "unknown error"}
• Invalid domain graph: ${result.fatal ?? "unknown error"}

AI-assisted analysis of Egonex-AI/Understand-Anything@32944829e7 (2026-08-12). Data as JSON: /api/errors/afb4cf985c0f49fb. Report an issue: GitHub.