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

autoresearch candidate artifact description is required

Error message

autoresearch candidate artifact description is required

What it means

The required description field must be present and a string. It carries the human-readable summary of what the candidate change does.

Source

Thrown at src/autoresearch/runtime.ts:1042

  } catch {
    throw new Error('autoresearch candidate artifact must be valid JSON');
  }
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw new Error('autoresearch candidate artifact must be a JSON object');
  }
  const record = parsed as Record<string, unknown>;
  const status = record.status;
  if (status !== 'candidate' && status !== 'noop' && status !== 'abort' && status !== 'interrupted') {
    throw new Error('autoresearch candidate artifact status must be candidate|noop|abort|interrupted');
  }
  if (record.candidate_commit !== null && typeof record.candidate_commit !== 'string') {
    throw new Error('autoresearch candidate artifact candidate_commit must be string|null');
  }
  if (typeof record.base_commit !== 'string' || !record.base_commit.trim()) {
    throw new Error('autoresearch candidate artifact base_commit is required');
  }
  if (typeof record.description !== 'string') {
    throw new Error('autoresearch candidate artifact description is required');
  }
  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> {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

  1. Always include a non-null string description in the artifact, even for noop/abort (e.g. 'no change needed')
  2. Update the worker prompt/template with a full example artifact showing description populated on every status
  3. Validate required fields in the worker harness before writing the artifact file

Example fix

// before
{"status":"noop","base_commit":"abc","candidate_commit":null,"notes":[]}
// after
{"status":"noop","base_commit":"abc","candidate_commit":null,"description":"no change required","notes":[]}
Defensive patterns

Strategy: validation

Validate before calling

const parsed = JSON.parse(raw) as Record<string, unknown>;
if (typeof parsed.description !== 'string' || parsed.description.length === 0) {
  throw new Error('artifact description missing; worker must summarize the change');
}

Type guard

function hasDescription(v: unknown): v is { description: string } {
  return typeof v === 'object' && v !== null && typeof (v as any).description === 'string';
}

Try / catch

try { const a = parseAutoresearchCandidateArtifact(raw); }
catch (e) { if (e instanceof Error && e.message.includes('description is required')) { /* add a string summary, e.g. 'no change required', and retry */ } throw e; }

Prevention

When it happens

Trigger: A worker omitting description entirely, or emitting it as a non-string (number, object, null) — commonly when the model returns the summary only in prose outside the JSON artifact.

Common situations: Models putting the description in surrounding text instead of the JSON, template branches that skip description for noop/abort statuses even though it is required, or description: null placeholders.

Related errors

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