openai/codex-plugin-cc · error · Error

Unsupported reasoning effort "${effort}". Use one of: none,

Error message

Unsupported reasoning effort "${effort}". Use one of: none, minimal, low, medium, high, xhigh.

What it means

normalizeReasoningEffort validates the --effort flag against the fixed set VALID_REASONING_EFFORTS = {none, minimal, low, medium, high, xhigh}. The value is trimmed and lowercased before comparison, so case/whitespace differences are tolerated; only genuinely unknown tokens throw. The valid set is a codex app-server protocol contract.

Source

Thrown at plugins/codex/scripts/codex-companion.mjs:123

    return null;
  }
  const normalized = String(model).trim();
  if (!normalized) {
    return null;
  }
  return MODEL_ALIASES.get(normalized.toLowerCase()) ?? normalized;
}

function normalizeReasoningEffort(effort) {
  if (effort == null) {
    return null;
  }
  const normalized = String(effort).trim().toLowerCase();
  if (!normalized) {
    return null;
  }
  if (!VALID_REASONING_EFFORTS.has(normalized)) {
    throw new Error(
      `Unsupported reasoning effort "${effort}". Use one of: none, minimal, low, medium, high, xhigh.`
    );
  }
  return normalized;
}

function normalizeArgv(argv) {
  if (argv.length === 1) {
    const [raw] = argv;
    if (!raw || !raw.trim()) {
      return [];
    }
    return splitRawArgumentString(raw);
  }
  return argv;
}

function parseCommandInput(argv, config = {}) {

View on GitHub (pinned to db52e28f4d)

Solutions

Use one of the exact allowed values: none, minimal, low, medium, high, xhigh.
If you need a new effort level, add it to VALID_REASONING_EFFORTS in codex-companion.mjs AND ensure the codex app-server accepts it.
Omit --effort entirely to let the default apply (normalizeReasoningEffort returns null for missing/empty).

Example fix

// before
codex-companion.mjs task --effort max "fix the bug"
// after
codex-companion.mjs task --effort high "fix the bug"

Defensive patterns

Strategy: validation

Validate before calling

const VALID = new Set(['none','minimal','low','medium','high','xhigh']);
if (effort != null && !VALID.has(String(effort).trim().toLowerCase())) {
  throw new Error(`Invalid effort: ${effort}`);
}

Type guard

/** @param {unknown} v @returns {v is string} */
function isValidEffort(v) {
  return typeof v === 'string' && VALID_REASONING_EFFORTS.has(v.trim().toLowerCase());
}

Prevention

Constrain effort selection in the UI to the six allowed values.
Document the allowed set next to any --effort input.

When it happens

Trigger: Running `codex-companion.mjs task --effort max` or any value outside the six allowed. Passing `--effort high` works; `--effort HIGH` also works due to toLowerCase(). A common miss is 'maximum' or 'ultra'.

Common situations: A model/UI change adds a new effort level but the companion set is not updated, or a user guesses a value from a different tool's vocabulary.

Related errors

AI-assisted analysis of openai/codex-plugin-cc@db52e28f4d (2026-08-13). Data as JSON: /api/errors/776a622e6ebd26da. Report an issue: GitHub.