Egonex-AI/Understand-Anything · error

Import extraction reported failures: ${preview}${suffix}

Error message

Import extraction reported failures: ${preview}${suffix}

What it means

refreshImportMap runs import extraction and collects per-file failures with a stage label. If any failure occurred it refuses to proceed, because a partial import map would produce an incomplete or wrong dependency graph for the incremental update.

Source

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

function refreshImportMap({ projectRoot, intermediateDir, previousScan, currentScan, analysisPaths }) {
  const inputPath = join(intermediateDir, 'incremental-import-input.json');
  const outputPath = join(intermediateDir, 'incremental-import-output.json');
  atomicWriteJson(inputPath, {
    projectRoot,
    files: currentScan.files,
    analysisPaths,
  });
  run(process.execPath, [IMPORT_SCRIPT, inputPath, outputPath]);
  const extraction = readJson(outputPath);
  const failures = Array.isArray(extraction?.failures) ? extraction.failures : [];
  if (failures.length > 0) {
    const preview = failures
      .slice(0, 5)
      .map(failure => `${failure.path ?? '<global>'} (${failure.stage})`)
      .join(', ');
    const suffix = failures.length > 5 ? ` (+${failures.length - 5} more)` : '';
    throw new Error(`Import extraction reported failures: ${preview}${suffix}`);
  }
  const selective = extraction?.importMap ?? {};
  const currentPaths = new Set(currentScan.files.map(file => file.path));
  const importMap = {};
  for (const file of currentScan.files) {
    const path = file.path;
    const candidate = Object.hasOwn(selective, path)
      ? selective[path]
      : previousScan?.importMap?.[path];
    importMap[path] = Array.isArray(candidate)
      ? sorted(candidate.filter(target => typeof target === 'string' && currentPaths.has(target)))
      : [];
  }
  return importMap;
}

function pruneExistingGraph(graph, pathsToReplace, importPathsToRefresh = new Set()) {
  const removedNodeIds = new Set();

View on GitHub (pinned to 07edf82a04)

Solutions

1. Inspect the failure preview in the message — it lists path and stage for each failing file
2. Fix or exclude the listed files (--exclude <patterns>) if they are irrelevant
3. Re-run after confirming the files parse correctly; transient states (mid-edit files) resolve on retry
4. If extraction is systematically failing after an update, re-run the full /understand pipeline to rebuild the import map

Example fix

// before
if (failures.length > 0) {
  throw new Error(`Import extraction reported failures: ${preview}${suffix}`);
}
// after
if (failures.length > 0) {
  console.warn(`Import extraction failures (proceeding): ${preview}${suffix}`);
}

function extractionSucceeded(extraction) { return extraction && Array.isArray(extraction.failures) && extraction.failures.length === 0; }

try {
  await prepareIncremental(args);
} catch (err) {
  if (String(err.message).startsWith('Import extraction reported failures')) {
    console.error(err.message); // lists failing paths + stages
    // fix/exclude listed files, or fall back to full analysis
  }
  throw err;
}

When it happens

Trigger: The import-extraction step returns an extraction object whose failures array is non-empty — e.g. files with syntax the extractor cannot parse, unreadable files, or a global extraction-stage error.

Common situations: Recently added source files in a syntax the extractor does not support, files deleted between scan and extraction, extractor version drift after a plugin update, or corrupt/unparseable source committed to the repo.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• Architecture update requires layers.json; baseline not advan
• Architecture update requires tour.json; baseline not advance
• Unresolved incremental symbol loss; baseline not advanced
• Invalid ${kind} path in git diff
• Invalid path in git diff for status ${status}

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