Yeachan-Heo/oh-my-codex · error · Error

autoresearch_candidate_missing:${candidateFile}

Error message

autoresearch_candidate_missing:${candidateFile}

What it means

readCandidateArtifact loads the candidate artifact file recorded in the run manifest, and this error means that file does not exist on disk. The path is embedded in the message so you can see exactly which file is missing. It typically indicates the run directory was partially deleted or the artifact was never written.

Source

Thrown at src/autoresearch/runtime.ts:1062

  if (!Array.isArray(record.notes) || record.notes.some((note) => typeof note !== 'string')) {
    throw new Error('autoresearch candidate artifact notes must be a string array');
  }
  if (typeof record.created_at !== 'string' || !record.created_at.trim()) {
    throw new Error('autoresearch candidate artifact created_at is required');
  }
  return {
    status,
    candidate_commit: record.candidate_commit,
    base_commit: record.base_commit,
    description: record.description,
    notes: record.notes,
    created_at: record.created_at,
  };
}

async function readCandidateArtifact(candidateFile: string): Promise<AutoresearchCandidateArtifact> {
  if (!existsSync(candidateFile)) {
    throw new Error(`autoresearch_candidate_missing:${candidateFile}`);
  }
  return parseAutoresearchCandidateArtifact(await readFile(candidateFile, 'utf-8'));
}

async function finalizeRun(
  manifest: AutoresearchRunManifest,
  projectRoot: string,
  updates: { status: AutoresearchRunStatus; stopReason: string },
): Promise<void> {
  manifest.status = updates.status;
  manifest.stop_reason = updates.stopReason;
  manifest.completed_at = nowIso();
  await writeRunManifest(manifest);
  await updateModeState('autoresearch', {
    active: false,
    current_phase: updates.status,
    completed_at: manifest.completed_at,
    stop_reason: updates.stopReason,

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Check the path in the error message and the run manifest's candidate_file field; restore or recreate the file
2. If the run never completed, start a new autoresearch run rather than resuming the broken one
3. Ensure run directories are not excluded by .gitignore/cleanup tools if you intend to resume them

import { existsSync } from 'fs';
if (!existsSync(candidateFile)) { /* start a new run or restore the file */ }

try { await readCandidateArtifact(file); } catch (e) { if ((e as Error).message.startsWith('autoresearch_candidate_missing:')) { /* re-run or skip resume */ } throw e; }

When it happens

Trigger: Calling readCandidateArtifact(candidateFile) (via resume/finalize flows) when existsSync(candidateFile) is false — e.g. the run dir was cleaned, the file was renamed, or an interrupted run never produced a candidate artifact.

Common situations: Manually pruning .autoresearch run directories, syncing a repo without untracked artifact files, or resuming a run that aborted before the candidate step completed.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• No mission summary found at ${summaryPath}.
• No autoresearch-goal mission found at ${repoRelative(cwd, pa
• Invalid autoresearch-goal mission at ${repoRelative(cwd, pat
• Autoresearch goal ${mission.slug} is already complete; creat
• Autoresearch goal ${mission.slug} cannot complete until prof

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/a6343508238b3159. Report an issue: GitHub.