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

${name} is required

Error message

${name} is required

What it means

normalizeString is the shared input validator for Hermes bridge MCP tool arguments; it throws 'X is required' when a required argument (cwd, sessionId, status, questionId, prompt, actor) is null/undefined. MCP tool calls arrive as loosely typed JSON, so missing keys are common client mistakes.

Source

Thrown at src/mcp/hermes-bridge.ts:136

const DEFAULT_TAIL_LINES = 80;
const MAX_TAIL_LINES = 500;
const MAX_TAIL_READ_BYTES = 256_000;
const OMX_INSTANCE_OPTION = "@omx_instance_id";

function jsonResult<T extends Record<string, unknown>>(data: T): HermesBridgeResult<T> {
  return { ok: true, data };
}

function failure<T extends Record<string, unknown> = Record<string, unknown>>(
  code: HermesBridgeFailureCode,
  error: string,
): HermesBridgeResult<T> {
  return { ok: false, code, error };
}

function normalizeString(value: unknown, name: string, options: { required?: boolean } = {}): string | undefined {
  if (value == null) {
    if (options.required) throw new Error(`${name} is required`);
    return undefined;
  }
  if (typeof value !== "string") throw new Error(`${name} must be a string`);
  const trimmed = value.trim();
  if (!trimmed && options.required) throw new Error(`${name} must be non-empty`);
  return trimmed || undefined;
}

function requireMutation(args: Record<string, unknown>): void {
  if (args.allow_mutation !== true) {
    throw new Error("mutating Hermes bridge tools require allow_mutation: true");
  }
}

function normalizePositiveInteger(value: unknown, fallback: number, max: number): number {
  if (value == null) return fallback;
  const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
  if (!Number.isInteger(parsed) || parsed <= 0) return fallback;

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Include the required field named in the error message with a non-null value
2. Check the tool's input schema for required parameter names
3. Upgrade client and server to matching versions if a field was renamed

Example fix

// before
hermesSendPrompt({ session_id: "s1" })
// after
hermesSendPrompt({ session_id: "s1", prompt: "continue" })

for (const k of ['session_id','prompt']) { if (args[k] == null) throw new Error(`${k} required`); }

function hasRequired<T extends object, K extends string>(o: T, k: K): o is T & Record<K,string> { return o[k] != null; }

catch (e) { if ((e as Error).message.endsWith('is required')) { /* fill missing field and retry */ } }

When it happens

Trigger: Calling a Hermes bridge tool without a required key, e.g. hermesSendPrompt({args:{}}) where prompt is required, or passing explicit null for a required field.

Common situations: MCP client omitting a field, wrong tool parameter name (prompt vs input), or a schema/client version mismatch where a field was renamed.

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

• Unknown MCP target: ${firstArg} ${MCP_SERVE_USAGE}
• ${name} must be a string
• ${name} must be non-empty
• mutation_not_allowed
• unsupported_session_kind

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