Egonex-AI/Understand-Anything · error

Symbol retry requires a partial or architecture incremental

Error message

Symbol retry requires a partial or architecture incremental update

What it means

The symbol retry mechanism is only valid for incremental plans whose action is PARTIAL_UPDATE or ARCHITECTURE_UPDATE. After loading the persisted plan, the script validates plan.action against this whitelist and throws when the action is anything else (e.g. FULL_REBUILD), because a targeted symbol retry is meaningless or unsafe for that update type.

Source

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

import { existsSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import {
  atomicWriteJson,
  getIntermediateDir,
  loadSymbolContext,
  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));

View on GitHub (pinned to 07edf82a04)

Solutions

1. Check the persisted plan's action (intermediate dir plan JSON) and only run symbol retry when it is PARTIAL_UPDATE or ARCHITECTURE_UPDATE.
2. For other actions (e.g. full rebuild), re-run the corresponding prepare step instead of the symbol retry script.
3. If the plan file is stale, regenerate it by re-running the incremental prepare for the current commits, then retry.

Example fix

// before
// plan.action === 'FULL_REBUILD'
node prepare-symbol-retry.mjs .
// Error: Symbol retry requires a partial or architecture incremental update
// after: rerun the matching prepare step first
node prepare-incremental.mjs .   # produces PARTIAL_UPDATE plan
node prepare-symbol-retry.mjs .  # passes

import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
const plan = JSON.parse(readFileSync(join(intermediateDir, 'incremental-plan.json'), 'utf-8'));
if (!['PARTIAL_UPDATE', 'ARCHITECTURE_UPDATE'].includes(plan.action)) {
  throw new Error(`Skip symbol retry; plan.action=${plan.action}`);
}

const isRetryablePlan = (plan) =>
  plan && (plan.action === 'PARTIAL_UPDATE' || plan.action === 'ARCHITECTURE_UPDATE');

try {
  await runRetry(projectRoot);
} catch (e) {
  if (e.message.includes('Symbol retry requires a partial or architecture')) {
    // fall back to the prepare step matching the plan's action
  } else throw e;
}

When it happens

Trigger: Running prepare-symbol-retry.mjs in a project whose intermediate incremental-symbol-retry/plan state records an action other than PARTIAL_UPDATE or ARCHITECTURE_UPDATE — most commonly after a full rebuild was planned, or after the plan file was written by a different pipeline stage.

Common situations: Developer assumed retry works after any failure, but the last plan was a FULL_REBUILD; stale plan file in the data directory from an older run with a different action; hand-edited or migrated intermediate state.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Symbol retry already used for these commits; stop without ad
• Project scan reported failures: ${preview}${suffix}
• Project scan omitted tracked, non-ignored files: ${unexplain
• No unresolved symbol files eligible for a targeted retry; in
• Retry batching failed: ${batching.error ?? batching.status}

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