Symbol retry already used for these commits; stop without ad

Error message

Symbol retry already used for these commits; stop without advancing the baseline

What it means

The script enforces a one-shot retry policy: if a retry record exists for the same baseCommit and headCommit with attempt === 1, the retry has already been consumed and it throws, instructing the caller to stop without advancing the baseline. This prevents infinite retry loops against the same commit pair.

Source

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

  normalizePath,
  readJson,
  symbolKind,
  validateIncrementalSymbols,
} from './validate-incremental-symbols.mjs';

async function main() {
  if (process.argv.length !== 3) throw new Error('Usage: node prepare-symbol-retry.mjs <projectRoot>');
  const projectRoot = realpathSync(process.argv[2]);
  const intermediateDir = await getIntermediateDir(projectRoot);
  const { plan, baseline } = loadSymbolContext(projectRoot, intermediateDir);
  if (!['PARTIAL_UPDATE', 'ARCHITECTURE_UPDATE'].includes(plan.action)) {
    throw new Error('Symbol retry requires a partial or architecture incremental update');
  }
  const retryPath = join(intermediateDir, 'incremental-symbol-retry.json');
  if (existsSync(retryPath)) {
    const retry = readJson(retryPath);
    if (retry.baseCommit === plan.baseCommit && retry.headCommit === plan.headCommit && retry.attempt === 1) {
      throw new Error('Symbol retry already used for these commits; stop without advancing the baseline');
    }
  }
  // Do not trust an old report or a caller-supplied list of files to replace.
  const report = await validateIncrementalSymbols(projectRoot, { intermediateDir });
  if (report.ok || report.unresolvedFiles.length === 0) {
    throw new Error('No unresolved symbol files eligible for a targeted retry; inspect the symbol report');
  }
  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}`);

View on GitHub (pinned to 07edf82a04)

Solutions

Stop retrying for these commits — the baseline must not advance via this path; run the normal incremental/full update instead.
Delete or move incremental-symbol-retry.json only if you are certain the previous retry never executed its batches (this is a deliberate operator decision).
Advance the commits (new HEAD) so the retry record no longer matches the current base/head pair.

Example fix

// before: second attempt for same commits
node prepare-symbol-retry.mjs .
// Error: Symbol retry already used for these commits; stop without advancing the baseline
// after: perform the regular incremental update instead
node prepare-incremental.mjs .

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
const retryPath = join(intermediateDir, 'incremental-symbol-retry.json');
if (existsSync(retryPath)) {
  const retry = JSON.parse(readFileSync(retryPath, 'utf-8'));
  if (retry.attempt === 1 && retry.baseCommit === base && retry.headCommit === head) {
    console.error('Retry already consumed for these commits; do not advance baseline.');
    process.exit(1);
  }
}

Try / catch

try {
  await runRetry(projectRoot);
} catch (e) {
  if (e.message.includes('Symbol retry already used')) {
    // stop; run the normal incremental update instead of advancing baseline
  } else throw e;
}

Prevention

Track retry consumption in CI so the script is invoked at most once per commit pair.
Never delete incremental-symbol-retry.json as an automatic retry tactic.
Advance to a new HEAD before attempting another retry.

When it happens

Trigger: Running prepare-symbol-retry.mjs a second time for the same base/head commit pair after a previous retry wrote incremental-symbol-retry.json with attempt 1.

Common situations: Re-running the retry script hoping a second attempt will help; CI retrying the script automatically; leftover retry record from a partially failed earlier run for the same commits.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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