What causes "model name cannot be empty" in jackwener/OpenCLI?

Pass a model or reasoning-level name: `opencli codex model "gpt-5.5"` or `opencli codex model high`.

jackwener/OpenCLI · error · ArgumentError

model name cannot be empty

Error message

model name cannot be empty

What it means

`findUniqueModelOption` in clis/codex/model.js normalizes the requested model name and matches it against the model/reasoning labels scraped from the Codex model menu. This ArgumentError is thrown when the normalized name is empty — i.e., no model name was supplied to the `codex model` command while not in list mode. The library treats an empty target as a caller mistake, not a lookup failure.

Source

Thrown at clis/codex/model.js:48

        .replace(/\s+/g, ' ')
        .trim();
}

const REASONING_OPTIONS = ['extra high', 'medium', 'high', 'low', 'auto', 'fast', 'speed', 'pro'];

function extractReasoning(value) {
    return REASONING_OPTIONS.find(option => value === option || value.endsWith(` ${option}`)) || '';
}

function extractModelVersion(value) {
    const match = value.match(/(?:^|\s)(\d+(?:\.\d+)?)(?=\s|$)/);
    return match?.[1] || '';
}

export function findUniqueModelOption(labels, rawName) {
    const name = normalizeModelText(rawName);
    if (!name) {
        throw new ArgumentError('model name cannot be empty');
    }
    const normalized = labels.map((label) => ({ label, normalized: normalizeModelText(label) }));
    const exact = normalized.filter(item => item.normalized === name);
    if (exact.length === 1) {
        return exact[0].label;
    }
    if (exact.length > 1) {
        throw new CommandExecutionError(`Model name "${rawName}" is ambiguous.`, `Matches: ${exact.map(item => item.label).join(', ')}`);
    }
    const partial = normalized.filter(item => item.normalized.includes(name));
    if (partial.length === 1) {
        return partial[0].label;
    }
    if (partial.length > 1) {
        throw new CommandExecutionError(`Model name "${rawName}" is ambiguous.`, `Matches: ${partial.map(item => item.label).join(', ')}`);
    }
    return null;
}

View on GitHub (pinned to 49907e53dc)

Solutions

Pass a model or reasoning-level name: `opencli codex model "gpt-5.5"` or `opencli codex model high`.
Use `opencli codex model --list` to see available options when you don't know the exact name.
Fix the calling script/config so the variable holding the model name is non-empty before invoking.
If calling the API directly, validate the name is non-empty before calling findUniqueModelOption, or handle ArgumentError.

Example fix

// before
const name = process.env.CODEX_MODEL; // may be undefined
const selected = findUniqueModelOption(labels, name); // throws ArgumentError
// after
const name = process.env.CODEX_MODEL;
if (!name || !name.trim()) throw new Error('CODEX_MODEL must be set, e.g. gpt-5.5');
const selected = findUniqueModelOption(labels, name);

Defensive patterns

Strategy: validation

Validate before calling

const name = (kwargs.name || '').trim();
if (!name) {
  // read-only mode: fetch current model instead of switching
  return run('opencli codex model'); // no args returns active model
}

Type guard

function isValidModelName(v) { return typeof v === 'string' && v.trim().length > 0; }

Try / catch

try {
  await switchModel(name);
} catch (err) {
  if (err instanceof ArgumentError && /cannot be empty/.test(err.message)) {
    // fall back to reading the active model or prompt for a name
  } else throw err;
}

Prevention

Always pass a non-empty positional name when switching
Default empty-name invocations to --list or the read path
Validate env/config variables holding model names before invoking
Check shell quoting so $MODEL isn't expanded to empty

When it happens

Trigger: Calling `opencli codex model` with no positional name and without `--list` in a code path where the empty-name short-circuit (returning the active model) was bypassed — e.g., invoking findUniqueModelOption directly or via `selected` with an empty/whitespace-only rawName.

Common situations: Scripting the CLI with a shell variable that is empty (`MODEL="" opencli codex model "$MODEL"`); passing only whitespace; a config file with a missing `model:` key; calling the exported helper with null/undefined in tests or integrations.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/d3c7daf82cff58ad. Report an issue: GitHub.