Project scan omitted tracked, non-ignored files: ${unexplain

Error message

Project scan omitted tracked, non-ignored files: ${unexplainedMissingFiles.slice(0, 10).join(', ')}. Baseline not advanced.

What it means

After scanning, the script compares the git-tracked, non-ignored file inventory against the scan results. Any tracked file that is missing from the scan, not ignored, and not an excluded tracked symlink is 'unexplained missing' — evidence the scan under-reported — so the baseline is not advanced and this error is thrown listing up to 10 such paths. Advancing the baseline on an incomplete scan would permanently lose those files from the graph.

Source

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

  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),
  );
  if (unexplainedMissingFiles.length > 0) {
    throw new Error(
      `Project scan omitted tracked, non-ignored files: ` +
      `${unexplainedMissingFiles.slice(0, 10).join(', ')}. Baseline not advanced.`,
    );
  }

  const generatedArtifactFiles = sorted(diffPaths.filter(isGeneratedArtifact));
  const nonGeneratedDiffPaths = diffPaths.filter(path => !isGeneratedArtifact(path));
  const deletedFiles = sorted(oldInventory.filter(path => !currentInventorySet.has(path)));
  const ignoredFiles = sorted(
    nonGeneratedDiffPaths.filter(
      path => !currentInventorySet.has(path) && !oldInventorySet.has(path),
    ),
  );
  const currentChangedPaths = sorted([
    ...nonGeneratedDiffPaths.filter(path => currentInventorySet.has(path)),
    ...currentInventory.filter(path => !oldInventorySet.has(path)),
  ]);

View on GitHub (pinned to 07edf82a04)

Solutions

Inspect the listed paths: confirm they are tracked (git ls-files <path>) and not ignored (git check-ignore <path>).
Reconcile the scanner's ignore configuration with .gitignore — remove overly aggressive ignore patterns that exclude tracked files.
Re-run the project scan; if files are still missing, clear any scan cache/intermediate state and rescan from scratch.
If the files are symlinks, verify isTrackedSymlink handling and consider replacing symlinks with real files or ignoring them consistently in git too.

Example fix

// before: scanner ignore stricter than gitignore, scan omits tracked file
Error: Project scan omitted tracked, non-ignored files: src/generated/api.ts. Baseline not advanced.
// after: align scanner ignores with git
// remove 'src/generated/' from the scanner's ignore config (it IS tracked)
git add -f src/generated/api.ts && node prepare-incremental.mjs .  # passes

Defensive patterns

Strategy: validation

Validate before calling

import { execSync } from 'node:child_process';
function findUnexplained(root, scannedPaths) {
  const tracked = new Set(execSync('git ls-files', { cwd: root }).toString().split('\n').filter(Boolean));
  const scanned = new Set(scannedPaths);
  return [...tracked].filter(p => !scanned.has(p) && !isIgnored(root, p));
}

Try / catch

try {
  await prepareIncremental(projectRoot);
} catch (e) {
  if (e.message.includes('Project scan omitted tracked, non-ignored files')) {
    // diff scanner ignores vs .gitignore for the listed paths, fix config, rescan
  } else throw e;
}

Prevention

Keep the scanner's ignore rules a superset-consistent mirror of .gitignore.
Add a CI check comparing git ls-files against the scan inventory.
Rescan from scratch after changing ignore configuration.

When it happens

Trigger: Running prepare-incremental.mjs when the current scan omitted files that git tracks: e.g. the scanner's ignore filter diverges from git's, symlinks are misclassified, or the scan hit an internal limit and silently skipped files.

Common situations: Custom ignore rules (e.g. a .uaignore or scanner config) that are stricter than .gitignore; a scanner bug or older scan cache; symlinked files inside the repo; large repos where the scan truncated results.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

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