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

sandbox.md frontmatter evaluator.command is required.

Error message

sandbox.md frontmatter evaluator.command is required.

What it means

parseSandboxContract throws EVALUATOR_COMMAND_ERROR when the evaluator block exists but its command is missing or trims to an empty string. evaluator.command is the executable command the sandbox runs to evaluate results, so an empty value makes the contract unusable.

Source

Thrown at src/autoresearch/contracts.ts:166

  const { frontmatter, body } = extractFrontmatter(content);
  const parsedFrontmatter = parseSimpleYamlFrontmatter(frontmatter);
  const evaluatorRaw = parsedFrontmatter.evaluator;

  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,
  };
}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Add 'command: <shell command>' nested under evaluator, e.g. 'command: ./evaluate.sh'.
2. Verify the command line is indented under the evaluator section (one level).
3. Ensure the value is non-empty after trimming.

Example fix

# before
evaluator:
  format: json

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

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

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

try {
  parseSandboxContract(content);
} catch (err) {
  if ((err as Error).message.includes('evaluator.command is required')) {
    // add non-empty 'command:' under the evaluator section
  }
  throw err;
}

When it happens

Trigger: Frontmatter with an evaluator block but no 'command:' key, 'command:' with no value, or 'command: " "' (whitespace only, trimmed to empty).

Common situations: Authoring sandbox.md and forgetting the command; placeholder text left as empty; indentation mistakes that put command at the wrong nesting level so it never lands in the evaluator object.

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.format is required and must
• 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/7cf693a7a8603ab5. Report an issue: GitHub.