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

sandbox.md frontmatter evaluator.format is required and must

Error message

sandbox.md frontmatter evaluator.format is required and must be json in autoresearch v1.

What it means

parseSandboxContract throws EVALUATOR_FORMAT_REQUIRED_ERROR when evaluator.format is absent or trims to empty. Autoresearch v1 requires the evaluator's output format to be declared explicitly; there is no default.

Source

Thrown at src/autoresearch/contracts.ts:169

  if (!evaluatorRaw || typeof evaluatorRaw !== 'object' || Array.isArray(evaluatorRaw)) {
    throw contractError(EVALUATOR_BLOCK_ERROR);
  }

  const evaluator = evaluatorRaw as { command?: unknown; format?: unknown; keep_policy?: unknown };
  const command = typeof evaluator.command === 'string'
    ? evaluator.command.trim()
    : '';
  const format = typeof evaluator.format === 'string'
    ? evaluator.format.trim().toLowerCase()
    : '';
  const keepPolicy = parseKeepPolicy(evaluator.keep_policy);

  if (!command) {
    throw contractError(EVALUATOR_COMMAND_ERROR);
  }
  if (!format) {
    throw contractError(EVALUATOR_FORMAT_REQUIRED_ERROR);
  }
  if (format !== 'json') {
    throw contractError(EVALUATOR_FORMAT_JSON_ERROR);
  }

  return {
    frontmatter: parsedFrontmatter,
    evaluator: {
      command,
      format: 'json',
      ...(keepPolicy ? { keep_policy: keepPolicy } : {}),
    },
    body,
  };
}

export function parseEvaluatorResult(raw: string): AutoresearchEvaluatorResult {
  let parsed: unknown;

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Add 'format: json' nested under evaluator.
2. Confirm the line is present and non-empty (only 'json' is accepted in v1).

Example fix

# before
evaluator:
  command: ./evaluate.sh

# after
evaluator:
  command: ./evaluate.sh
  format: json

function evaluatorFormatPresent(content: string): boolean {
  return /^[ \t]+format:\s*\S+/m.test(content);
}

const hasFormat = (ev: { format?: unknown }): boolean =>
  typeof ev.format === 'string' && ev.format.trim().length > 0;

try {
  parseSandboxContract(content);
} catch (err) {
  if ((err as Error).message.includes('evaluator.format is required')) {
    // add 'format: json' under evaluator
  }
  throw err;
}

When it happens

Trigger: Evaluator block with command but no 'format:' line, or 'format:' with only whitespace.

Common situations: Assuming json is the implicit default; deleting the format line while editing; copy-paste from an older template that omitted format.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• sandbox.md frontmatter evaluator.command is required.
• sandbox.md frontmatter must define an evaluator block.
• sandbox.md frontmatter evaluator.format must be json in auto
• ${filePath} frontmatter "${key}" must not be empty
• ${filePath} frontmatter "${key}" must be a single-line strin

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