Egonex-AI/Understand-Anything · error · Error

Import artifact does not match the required shape

Error message

Import artifact does not match the required shape

What it means

Thrown by validateImportArtifact in the large-repo benchmark harness when the JSON written by the extract-import-map worker fails a structural schema check. The harness refuses to feed a malformed import-map into the downstream batching stage, since a partial or truncated artifact would corrupt agent input sizing. It guards schemaVersion-less output by asserting scriptCompleted, an importMap record, a stats record with three non-negative integers, and that every importMap target list is an array of strings.

Source

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

  }
}

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'),
    )
  ) {
    throw new Error('Import artifact does not match the required shape');
  }
}

function validateBatchArtifact(batches) {
  if (
    !isRecord(batches) ||
    batches.schemaVersion !== 1 ||
    typeof batches.algorithm !== 'string' ||
    batches.algorithm.length === 0 ||
    !Array.isArray(batches.batches) ||
    !isNonNegativeInteger(batches.totalBatches) ||
    batches.totalBatches !== batches.batches.length ||
    batches.batches.some(
      (batch) =>
        !isRecord(batch) ||
        !isNonNegativeInteger(batch.batchIndex) ||
        !Array.isArray(batch.files) ||
        !isRecord(batch.batchImportData) ||

View on GitHub (pinned to 32944829e7)

Solutions

1. Re-run the import stage in isolation: node understand-anything-plugin/skills/understand/extract-import-map.mjs <input.json> <output.json> and inspect stderr for filesScanned/filesWithImports/totalEdges.
2. Open the offending import-map.json and confirm it has top-level scriptCompleted:true, importMap:{}, and stats:{filesScanned,filesWithImports,totalEdges} all >= 0 integers.
3. If scriptCompleted is false/missing, the worker exited early — check the worker stage stderr captured in report.stages.imports and fix the root cause (e.g. WASM grammar load failure) before re-running.
4. If you edited the artifact schema, regenerate it via the shipped worker rather than hand-authoring, so all fields are populated.
5. Clear the artifactRoot directory and re-run the full benchmark so no stale/partial import-map.json is reused.

Example fix

// before: hand-written minimal map missing stats envelope
{ "importMap": { "./a.ts": ["./b.ts"] } }

// after: full shape produced by extract-import-map.mjs
{
  "scriptCompleted": true,
  "stats": { "filesScanned": 1, "filesWithImports": 1, "totalEdges": 1 },
  "importMap": { "./a.ts": ["./b.ts"] }
}

import { readFileSync } from 'node:fs';
function isValidImportArtifact(v) {
  if (typeof v !== 'object' || v === null) return false;
  if (v.scriptCompleted !== true) return false;
  if (typeof v.importMap !== 'object' || v.importMap === null) return false;
  if (typeof v.stats !== 'object' || v.stats === null) return false;
  const s = v.stats;
  if (!Number.isInteger(s.filesScanned) || s.filesScanned < 0) return false;
  if (!Number.isInteger(s.filesWithImports) || s.filesWithImports < 0) return false;
  if (!Number.isInteger(s.totalEdges) || s.totalEdges < 0) return false;
  for (const targets of Object.values(v.importMap)) {
    if (!Array.isArray(targets)) return false;
    if (targets.some((t) => typeof t !== 'string')) return false;
  }
  return true;
}
// before feeding the artifact to the benchmark:
const artifact = JSON.parse(readFileSync(path, 'utf-8'));
if (!isValidImportArtifact(artifact)) throw new Error('refusing to feed malformed import artifact');

function isImportArtifact(v) {
  if (typeof v !== 'object' || v === null) return false;
  const o = v;
  return o.scriptCompleted === true
    && typeof o.importMap === 'object' && o.importMap !== null
    && typeof o.stats === 'object' && o.stats !== null
    && Number.isInteger(o.stats.filesScanned) && o.stats.filesScanned >= 0
    && Number.isInteger(o.stats.filesWithImports) && o.stats.filesWithImports >= 0
    && Number.isInteger(o.stats.totalEdges) && o.stats.totalEdges >= 0
    && Object.values(o.importMap).every(
        (t) => Array.isArray(t) && t.every((x) => typeof x === 'string'));
}

try {
  validateImportArtifact(imports);
} catch (e) {
  // the message is generic; log the offending file for diagnosis
  console.error('import-map.json shape invalid:', e.message, importPath);
  throw e;
}

When it happens

Trigger: The benchmark reads artifactRoot/import-map.json after the import stage exits cleanly and calls validateImportArtifact(imports). It throws when (a) scriptCompleted !== true (worker crashed before finalizing), (b) importMap or stats is not an object, (c) stats.filesScanned/filesWithImports/totalEdges is missing or negative/non-integer, or (d) any value in importMap is not an array, or any element of that array is not a string.

Common situations: An older extract-import-map.mjs version that omits the scriptCompleted flag or stats block (version drift between plugin cache and benchmark script). The WASM tree-sitter loader failing partway so importMap is populated for only some files. A manually edited or hand-written import-map.json missing the stats envelope. Disk-full / interrupted write producing a truncated JSON that JSON.parse happens to accept as a partial object.

Related errors

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

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