{"record":{"id":"d64c013026d57199","repo":"Egonex-AI/Understand-Anything","slug":"project-scan-reported-failures-preview-suffix","errorCode":null,"errorMessage":"Project scan reported failures: ${preview}${suffix}","messagePattern":"Project scan reported failures: (.+?)(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/prepare-incremental.mjs","lineNumber":541,"sourceCode":"      throw new Error('Previous graph commit does not match the requested base and no symbol baseline exists; cannot safely retry');\n    }\n    atomicWriteJson(baselineSnapshotPath, { baseCommit, scan: baselineScan, graph: baselineGraph });\n  }\n  // A failed prior attempt can leave complete or split analyzer batches behind.\n  // Remove only known internal scratch names before planning the retry so the\n  // merge cannot resurrect deleted nodes from stale output.\n  clearIncrementalScratch(intermediateDir);\n\n  const currentScanPath = join(intermediateDir, 'current-scan.json');\n  const currentScan = runScan(projectRoot, currentScanPath, args.excludePatterns);\n  const scanFailures = Array.isArray(currentScan?.failures) ? currentScan.failures : [];\n  if (scanFailures.length > 0) {\n    const preview = scanFailures\n      .slice(0, 5)\n      .map(failure => `${failure.path ?? '<global>'} (${failure.stage})`)\n      .join(', ');\n    const suffix = scanFailures.length > 5 ? ` (+${scanFailures.length - 5} more)` : '';\n    throw new Error(`Project scan reported failures: ${preview}${suffix}`);\n  }\n  const currentInventory = sorted(currentScan.files.map(file => file.path));\n  const currentInventorySet = new Set(currentInventory);\n  // The durable graph may have advanced before a failed fingerprints/meta save.\n  // Use only the preserved graph, even when retrying against a different HEAD.\n  const oldInventory = inventoryFrom(baselineScan, baselineGraph, oldFingerprints);\n  const oldInventorySet = new Set(oldInventory);\n  const trackedPaths = new Set(parseNulPaths(run(\n    'git',\n    ['ls-files', '--cached', '-z', '--', '.'],\n    { cwd: projectRoot },\n  )));\n  const currentIgnoreFilter = createIgnoreFilter(projectRoot, args.excludePatterns);\n  const unexplainedMissingFiles = oldInventory.filter(path =>\n    !currentInventorySet.has(path)\n    && trackedPaths.has(path)\n    && !currentIgnoreFilter.isIgnored(path)\n    && !isTrackedSymlink(projectRoot, path),","sourceCodeStart":523,"sourceCodeEnd":559,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/prepare-incremental.mjs#L523-L559","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the failing paths and stages from the error message (first 5 shown) and fix or repair those specific files (permissions, encoding, syntax).","Check whether the failing stage indicates a tool/parser bug and upgrade the plugin/version accordingly.","Exclude genuinely unscannable generated files from the project via ignore configuration so the scan skips them.","If failures were transient (network drive, EBUSY), re-run the scan/prepare step."],"exampleFix":"// before: unreadable file blocks incremental update\n$ node prepare-incremental.mjs .\nError: Project scan reported failures: src/generated/bundle.js (parse)\n// after: ignore the generated file so the scan succeeds\n// .gitignore or project ignore config\nsrc/generated/\n$ node prepare-incremental.mjs .  # passes","handlingStrategy":"validation","validationCode":"// run the scan check before invoking prepare\nimport { readdirSync, readFileSync } from 'node:fs';\nfunction assertScannable(root, paths) {\n  for (const p of paths) {\n    try { readFileSync(p, { encoding: 'utf-8' }); }\n    catch (e) { throw new Error(`File will fail scan: ${p}: ${e.message}`); }\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await prepareIncremental(projectRoot);\n} catch (e) {\n  if (e.message.startsWith('Project scan reported failures:')) {\n    // parse listed paths/stages, repair files or adjust ignores, then retry once\n  } else throw e;\n}","preventionTips":["Keep generated/vendor files in ignore configuration so the scanner never attempts them.","Fix file permissions and encodings before running incremental updates.","Run the full scan first and resolve all failures before enabling incremental mode."],"tags":["scan","incremental-update","fail-fast","filesystem"],"backgroundTag":"schema-validation-failed","analyzedSha":"07edf82a04371b6f69779b067bdc8a1a8753a9db","analyzedAt":"2026-09-07T23:20:10.829Z","contentChangedAt":"2026-09-07T23:20:10.829Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}