Egonex-AI/Understand-Anything · error

Project scan reported failures: ${preview}${suffix}

Error message

Project scan reported failures: ${preview}${suffix}

What it means

prepare-incremental.mjs runs a fresh project scan as part of preparing an incremental knowledge-graph update. If any file failed to scan (scanFailures is non-empty), the script refuses to compute a baseline/inventory and throws with a preview listing up to 5 failed paths and their failure stage, plus a count of any remaining failures. This is a fail-fast guard: building a diff from a partial scan would silently drop files from the graph.

Source

Thrown at understand-anything-plugin/skills/understand/prepare-incremental.mjs:541

      throw new Error('Previous graph commit does not match the requested base and no symbol baseline exists; cannot safely retry');
    }
    atomicWriteJson(baselineSnapshotPath, { baseCommit, scan: baselineScan, graph: baselineGraph });
  }
  // A failed prior attempt can leave complete or split analyzer batches behind.
  // Remove only known internal scratch names before planning the retry so the
  // merge cannot resurrect deleted nodes from stale output.
  clearIncrementalScratch(intermediateDir);

  const currentScanPath = join(intermediateDir, 'current-scan.json');
  const currentScan = runScan(projectRoot, currentScanPath, args.excludePatterns);
  const scanFailures = Array.isArray(currentScan?.failures) ? currentScan.failures : [];
  if (scanFailures.length > 0) {
    const preview = scanFailures
      .slice(0, 5)
      .map(failure => `${failure.path ?? '<global>'} (${failure.stage})`)
      .join(', ');
    const suffix = scanFailures.length > 5 ? ` (+${scanFailures.length - 5} more)` : '';
    throw new Error(`Project scan reported failures: ${preview}${suffix}`);
  }
  const currentInventory = sorted(currentScan.files.map(file => file.path));
  const currentInventorySet = new Set(currentInventory);
  // The durable graph may have advanced before a failed fingerprints/meta save.
  // Use only the preserved graph, even when retrying against a different HEAD.
  const oldInventory = inventoryFrom(baselineScan, baselineGraph, oldFingerprints);
  const oldInventorySet = new Set(oldInventory);
  const trackedPaths = new Set(parseNulPaths(run(
    'git',
    ['ls-files', '--cached', '-z', '--', '.'],
    { cwd: projectRoot },
  )));
  const currentIgnoreFilter = createIgnoreFilter(projectRoot, args.excludePatterns);
  const unexplainedMissingFiles = oldInventory.filter(path =>
    !currentInventorySet.has(path)
    && trackedPaths.has(path)
    && !currentIgnoreFilter.isIgnored(path)
    && !isTrackedSymlink(projectRoot, path),

View on GitHub (pinned to 07edf82a04)

Solutions

1. Read the failing paths and stages from the error message (first 5 shown) and fix or repair those specific files (permissions, encoding, syntax).
2. Check whether the failing stage indicates a tool/parser bug and upgrade the plugin/version accordingly.
3. Exclude genuinely unscannable generated files from the project via ignore configuration so the scan skips them.
4. If failures were transient (network drive, EBUSY), re-run the scan/prepare step.

Example fix

// before: unreadable file blocks incremental update
$ node prepare-incremental.mjs .
Error: Project scan reported failures: src/generated/bundle.js (parse)
// after: ignore the generated file so the scan succeeds
// .gitignore or project ignore config
src/generated/
$ node prepare-incremental.mjs .  # passes

// run the scan check before invoking prepare
import { readdirSync, readFileSync } from 'node:fs';
function assertScannable(root, paths) {
  for (const p of paths) {
    try { readFileSync(p, { encoding: 'utf-8' }); }
    catch (e) { throw new Error(`File will fail scan: ${p}: ${e.message}`); }
  }
}

try {
  await prepareIncremental(projectRoot);
} catch (e) {
  if (e.message.startsWith('Project scan reported failures:')) {
    // parse listed paths/stages, repair files or adjust ignores, then retry once
  } else throw e;
}

When it happens

Trigger: Running the incremental prepare step (main()) when the project scan produced one or more per-file failures — e.g. unreadable files, parse errors, or failures in an earlier stage recorded as {path, stage} entries in scanFailures.

Common situations: Files with unusual encodings or permissions mid-update; a parser stage choking on a newly added language; transient filesystem errors (network drives, symlinks); a corrupted file introduced by a bad merge.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Project scan omitted tracked, non-ignored files: ${unexplain
• Unable to remove temporary benchmark artifacts
• Repository path does not exist: ${repoValue}
• Repository path is not a directory: ${repoValue}
• --output must be outside the subject repository

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