Egonex-AI/Understand-Anything · error · Error

Scan artifact does not match the required shape

Error message

Scan artifact does not match the required shape

What it means

Thrown by validateScanArtifact when the scan stage's JSON output fails a structural guard. The validator checks that scan is an object with scriptCompleted===true, a files array, a totalFiles count equal to files.length, numeric filteredByIgnore and stats fields, string→count maps for byCategory/byLanguage, a 64-hex-char contentDigest, and that every file entry has a non-empty string path and a non-negative integer sizeLines. Any single violation throws.

Source

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

    !isNonNegativeInteger(scan.totalFiles) ||
    scan.totalFiles !== scan.files.length ||
    !isNonNegativeInteger(scan.filteredByIgnore) ||
    !isRecord(scan.stats) ||
    !isNonNegativeInteger(scan.stats.filesScanned) ||
    scan.stats.filesScanned !== scan.totalFiles ||
    !isStringCountMap(scan.stats.byCategory) ||
    !isStringCountMap(scan.stats.byLanguage) ||
    typeof scan.contentDigest !== 'string' ||
    !/^[a-f0-9]{64}$/.test(scan.contentDigest) ||
    scan.files.some(
      (file) =>
        !isRecord(file) ||
        typeof file.path !== 'string' ||
        file.path.length === 0 ||
        !isNonNegativeInteger(file.sizeLines),
    )
  ) {
    throw new Error('Scan artifact does not match the required shape');
  }
}

function validateImportArtifact(imports) {
  if (
    !isRecord(imports) ||
    imports.scriptCompleted !== true ||
    !isRecord(imports.importMap) ||
    !isRecord(imports.stats) ||
    !isNonNegativeInteger(imports.stats.filesScanned) ||
    !isNonNegativeInteger(imports.stats.filesWithImports) ||
    !isNonNegativeInteger(imports.stats.totalEdges) ||
    Object.values(imports.importMap).some(
      (targets) =>
        !Array.isArray(targets) ||
        targets.some((target) => typeof target !== 'string'),
    )
  ) {

View on GitHub (pinned to 32944829e7)

Solutions

1. Re-run the scan stage and confirm it exits cleanly (scriptCompleted===true).
2. Inspect the scan artifact to find the first failing field (files.length vs totalFiles, missing path, bad digest).
3. Ensure the scan script version matches the validator version (no schema drift).
4. Check worker stderr/diagnostics for the underlying abort cause and fix it, then regenerate.

Example fix

// before — scan artifact with scriptCompleted false triggers the throw
// after — ensure scan-project.mjs sets scriptCompleted=true on success and re-run
// (no code fix in the validator; repair the scan stage output)

function isValidScan(scan: unknown): boolean {
  if (scan === null || typeof scan !== 'object' || Array.isArray(scan)) return false;
  const s = scan as Record<string, any>;
  if (s.scriptCompleted !== true) return false;
  if (!Array.isArray(s.files) || s.totalFiles !== s.files.length) return false;
  if (!/^[a-f0-9]{64}$/.test(String(s.contentDigest))) return false;
  return s.files.every((f: any) => f && typeof f.path === 'string' && f.path.length > 0 && Number.isInteger(f.sizeLines) && f.sizeLines >= 0);
}

function isScanArtifact(v: unknown): boolean {
  return isValidScan(v); // wraps the structural check above as a narrowing predicate
}

try { validateScanArtifact(scan); } catch (e) { /* mark stage failed, capture stderr, do not proceed to import/batch stages */ throw e; }

When it happens

Trigger: The scan-project stage crashed or was killed, leaving scriptCompleted false or missing; totalFiles was miscounted relative to files.length; a file entry lacks path/sizeLines; contentDigest is absent or not a SHA-256; byCategory/byLanguage contain non-integer values; the artifact is not an object.

Common situations: A bug in scan-project.mjs that aborts before setting scriptCompleted; truncation of the output file; a schema change in scan output not reflected in the validator; memory/timeout killing the scan partway; manual edits to the scan artifact.

Related errors

• Import artifact does not match the required shape
• Batch artifact does not match the required shape
• Benchmark stage failed: ${stage.name}
• 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/48eb5af383ed9374. Report an issue: GitHub.