Egonex-AI/Understand-Anything · error

Invalid retry batch index

Error message

Invalid retry batch index

What it means

While annotating each retry batch with previous symbols, the script validates that batch.batchIndex is an integer >= 1. A missing, non-integer, zero, or negative batchIndex indicates a malformed batches file, so it throws before any batches are scheduled for execution.

Source

Thrown at understand-anything-plugin/skills/understand/prepare-symbol-retry.mjs:54

  }
  const paths = new Set(report.unresolvedFiles);
  const changedFilesPath = join(intermediateDir, 'incremental-symbol-retry-files.json');
  const batchesPath = join(intermediateDir, 'incremental-symbol-retry-batches.json');
  atomicWriteJson(changedFilesPath, [...paths]);
  const skillDir = dirname(fileURLToPath(import.meta.url));
  const batching = spawnSync(process.execPath, [
    join(skillDir, 'compute-batches.mjs'), projectRoot,
    `--changed-files=${changedFilesPath}`, `--output=${batchesPath}`,
  ], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
  if (batching.stderr) process.stderr.write(batching.stderr);
  if (batching.status !== 0) throw new Error(`Retry batching failed: ${batching.error ?? batching.status}`);
  const batches = readJson(batchesPath).batches;
  const scheduled = batches.flatMap(batch => batch.files.map(file => file.path));
  if (JSON.stringify([...scheduled].sort()) !== JSON.stringify([...paths].sort())) {
    throw new Error('Retry batches do not cover exactly the affected files');
  }
  for (const batch of batches) {
    if (!Number.isInteger(batch.batchIndex) || batch.batchIndex < 1) throw new Error('Invalid retry batch index');
    const files = new Set(batch.files.map(file => file.path));
    batch.previousSymbols = baseline.files.filter(file => files.has(file.filePath)).flatMap(file =>
      file.nodes.filter(symbolKind).map(node => {
        const parents = new Set(file.edges.filter(edge => edge.type === 'contains' && edge.target === node.id)
          .map(edge => edge.source));
        const owners = file.nodes.filter(parent => parent.type === 'class' && parents.has(parent.id))
          .map(parent => parent.name);
        return {
          id: node.id, name: node.name, type: node.type, filePath: node.filePath,
          ...(node.lineRange ? { lineRange: node.lineRange } : {}),
          ...(owners.length ? { owners } : {}),
        };
      }),
    );
    batch.missingSymbols = report.files.filter(file => files.has(file.filePath));
  }
  const assembled = readJson(join(intermediateDir, 'assembled-graph.json'));
  const candidates = readJson(join(intermediateDir, 'incremental-edge-candidates.json'));

View on GitHub (pinned to 07edf82a04)

Solutions

1. Delete incremental-symbol-retry-batches.json and re-run prepare-symbol-retry.mjs so a fresh, current-version batches file is generated.
2. Verify the installed compute-batches.mjs matches the plugin version (no mixed old/new files in the skill directory).
3. Inspect the batches JSON to confirm each batch has an integer batchIndex >= 1; fix the generator if it emits 0-based indices.

Example fix

// before: 0-based index from old batching
{"batchIndex": 0, "files": [...]} → Error: Invalid retry batch index
// after: regenerate with current script
rm .ua/intermediate/incremental-symbol-retry-batches.json
node prepare-symbol-retry.mjs .  // batches now use 1-based indices

function assertValidBatches(batches) {
  batches.forEach((b, i) => {
    if (!Number.isInteger(b.batchIndex) || b.batchIndex < 1) {
      throw new Error(`Batch ${i} has invalid batchIndex: ${b.batchIndex}`);
    }
  });
}

const hasValidBatchIndex = (batch) =>
  typeof batch.batchIndex === 'number' && Number.isInteger(batch.batchIndex) && batch.batchIndex >= 1;

try {
  await runRetry(projectRoot);
} catch (e) {
  if (e.message === 'Invalid retry batch index') {
    // regenerate the batches file with the current compute-batches.mjs
  } else throw e;
}

When it happens

Trigger: compute-batches.mjs produced (or a stale file contains) batch objects lacking a valid batchIndex — schema drift between batching versions, hand-edited JSON, or a partially written batches output.

Common situations: Older compute-batches.mjs version that emitted 0-based indices or omitted batchIndex; a corrupted/truncated batches JSON after a crash during atomic write (unlikely) or manual editing; test fixtures copied into the intermediate directory.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Retry batching failed: ${batching.error ?? batching.status}
• Retry batches do not cover exactly the affected files
• Batch artifact does not match the required shape
• Symbol retry requires a partial or architecture incremental
• Symbol retry already used for these commits; stop without ad

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