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

autoresearch candidate artifact base_commit is required

Error message

autoresearch candidate artifact base_commit is required

What it means

The required base_commit field must be a non-empty trimmed string. It identifies the git commit the candidate was produced against and cannot be missing, empty, or whitespace-only.

Solutions

  1. Have the worker capture the base commit (git rev-parse HEAD) before starting and always write it as base_commit
  2. If the repo has no commits, create an initial empty commit so a base SHA exists
  3. Fix worker templates so base_commit is unconditionally populated, never conditionally omitted
  4. Fail loudly inside the worker if the base SHA cannot be read, instead of writing an empty value

Example fix

// before
{"status":"candidate","candidate_commit":"def","description":"...","notes":[]}
// after
{"status":"candidate","base_commit":"abc123","candidate_commit":"def456","description":"...","notes":[]}
Defensive patterns

Strategy: validation

Validate before calling

function isValidBaseCommit(v: unknown): boolean {
  return typeof v === 'string' && v.trim().length > 0;
}
const parsed = JSON.parse(raw) as Record<string, unknown>;
if (!isValidBaseCommit(parsed.base_commit)) throw new Error('artifact base_commit missing/empty');

Type guard

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

Try / catch

try { const a = parseAutoresearchCandidateArtifact(raw); }
catch (e) { if (e instanceof Error && e.message.includes('base_commit is required')) { /* capture git rev-parse HEAD and repopulate the artifact */ } throw e; }

Prevention

When it happens

Trigger: A worker omitting base_commit, emitting an empty string, whitespace, or a non-string value when it could not determine the base commit (e.g. empty repo, detached context, or a failed git call inside the worker).

Common situations: Workers running in repos with no commits yet, base SHA capture failing silently and defaulting to '', or templates that skip the field on some branches.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/autoresearch/runtime.ts:1039

  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } 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,
  };

View on GitHub (pinned to 3ad79a8a6f)