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

${guidance}Invalid reasoning mode "${mode}". Expected one of

Error message

${guidance}Invalid reasoning mode "${mode}". Expected one of: ${REASONING_MODES.join(", ")}.
${REASONING_USAGE}

What it means

The `omx reasoning` command rejects a reasoning mode that is not in REASONING_MODES, with tailored guidance for 'max' (configure via agentReasoning instead of the reasoning command) and 'ultra' (not an alias for max; only direct -c model_reasoning_effort passthrough exists).

Source

Thrown at src/cli/index.ts:3836

      console.log(`Current ${REASONING_KEY}: ${current}`);
      return;
    }

    console.log(`${REASONING_KEY} is not set in ${configPath}.`);
    console.log(REASONING_USAGE);
    return;
  }

  if (!REASONING_MODE_SET.has(mode)) {
    const unsupportedMode = isUnsupportedRootReasoningEffort(mode)
      ? normalizeUnsupportedRootReasoningEffort(mode)
      : undefined;
    const guidance = unsupportedMode === "max"
      ? `Reasoning mode "${mode}" is not supported by "omx reasoning".\nPer-agent "max" is configured with agentReasoning; direct -c model_reasoning_effort=... is passed to Codex and remains capability-dependent.\n`
      : unsupportedMode === "ultra"
        ? `Reasoning mode "${mode}" is not supported by OMX root or per-agent reasoning and is not an alias for "max".\nDirect -c model_reasoning_effort=... remains opaque Codex passthrough.\n`
        : "";
    throw new Error(
      `${guidance}Invalid reasoning mode "${mode}". Expected one of: ${REASONING_MODES.join(", ")}.\n${REASONING_USAGE}`,
    );
  }

  const { mkdir, readFile, writeFile } = await import("fs/promises");
  await mkdir(dirname(configPath), { recursive: true });

  const existing = existsSync(configPath)
    ? await readFile(configPath, "utf-8")
    : "";
  const updated = upsertTopLevelTomlString(existing, REASONING_KEY, mode);
  await writeFile(configPath, updated);
  console.log(`Set ${REASONING_KEY}="${mode}" in ${configPath}`);
}

export async function launchWithAuthHotswap(args: string[]): Promise<void> {
  const launchCwd = process.cwd();
  const { omxArgs, suffix } = splitOmxArgsAtEndOfOptions(args);

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Use one of the modes listed in the error's 'Expected one of' list
2. For 'max', configure it per-agent with agentReasoning in your agent config rather than the reasoning command
3. For arbitrary efforts, pass Codex config directly: -c model_reasoning_effort=... (capability-dependent passthrough)
4. Check REASONING_USAGE in the error text for the canonical invocation examples

Example fix

# before
$ omx reasoning max

# after
$ omx reasoning high   # or configure agentReasoning for max

const REASONING_MODES = ["minimal", "low", "medium", "high"]; // consult the error's list
if (!REASONING_MODES.includes(mode)) throw new UsageError(`use one of ${REASONING_MODES.join(", ")}`);

function isReasoningMode(m: string): boolean { return /^[a-z]+$/.test(m) && !['"max"', '"ultra"'].includes(m); }

try { await setReasoning(mode); } catch (e) { if (/Invalid reasoning mode/.test(e.message)) { printUsage(); } }

When it happens

Trigger: Running `omx reasoning <mode>` with a mode outside the allowed set — commonly `omx reasoning max` or `omx reasoning ultra`, or a typo like 'hight'.

Common situations: Users assuming CLI flags from other tools (e.g. -c model_reasoning_effort=high semantics) map to OMX modes; docs/blog examples referencing 'max'/'ultra' efforts; muscle memory from older OMX versions with different mode names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• agent name must not be empty
• invalid agent name: ${name}
• \"${trimmed}\" is reserved by Codex built-in agents
• [ask] invalid --agent-prompt role "${role}". Expected lowerc
• --answer-question-id requires --answer

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