jackwener/OpenCLI · error · ArgumentError

--model "${value}" is not a valid canonical model id. Expect

Error message

--model "${value}" is not a valid canonical model id. Expected format: version-variant (e.g. "2.5-flash", "3.1-pro"). Use "opencli gemini models" to list available values.

What it means

validateAskModelValue in clis/gemini/ask.js performs a final strict format check: the `--model` value must match `/^\d+\.\d+-[a-z][a-z-]*$/` (version-variant, e.g. `2.5-flash`, `3.1-pro`). Values that contain a version but fail the full canonical shape — extra characters, uppercase, underscores, wrong separator — trigger this ArgumentError.

Source

Thrown at clis/gemini/ask.js:67

function validateAskModelValue(value) {
    if (!value) {
        throw new ArgumentError(
            '--model requires a canonical model id (e.g. "2.5-flash"). ' +
            'Use "opencli gemini models" to list available values.'
        );
    }
    // Reject short aliases like "pro", "flash", "flash-lite" that lack a version number.
    if (!/\d+\.\d+/.test(value)) {
        throw new ArgumentError(
            '--model "' + value + '" is not accepted. ' +
            'Short aliases like "pro", "flash", or "flash-lite" are not supported. ' +
            'Use a canonical model id (e.g. "2.5-flash"). ' +
            'Use "opencli gemini models" to list available values.'
        );
    }
    // Must match canonical format: X.Y-variant
    if (!/^\d+\.\d+-[a-z][a-z-]*$/.test(value)) {
        throw new ArgumentError(
            '--model "' + value + '" is not a valid canonical model id. ' +
            'Expected format: version-variant (e.g. "2.5-flash", "3.1-pro"). ' +
            'Use "opencli gemini models" to list available values.'
        );
    }
}

export const __test__ = {
    validateAskModelValue,
};

export const askCommand = cli({
    site: 'gemini',
    name: 'ask',
    access: 'write',
    description: 'Send a prompt to Gemini and return only the assistant response',
    domain: GEMINI_DOMAIN,
    strategy: Strategy.COOKIE,

View on GitHub (pinned to 49907e53dc)

Solutions

1. Use only the `version-variant` portion: `--model 2.5-flash`, not `--model gemini-2.5-flash`
2. Strip any vendor prefix or suffix from the value you copied
3. Run `opencli gemini models` and copy a listed id verbatim

Example fix

// before
opencli gemini ask --model gemini-2.5-flash --prompt "hi"
// after
opencli gemini ask --model 2.5-flash --prompt "hi"

const v = String(args.model || '').trim();
if (!/^\d+\.\d+-[a-z][a-z-]*$/.test(v)) {
  throw new Error(`--model must be version-variant like 2.5-flash, got "${args.model}"`);
}

function isVersionVariant(v) {
  return typeof v === 'string' && /^\d+\.\d+-[a-z][a-z-]*$/.test(v);
}

try {
  await geminiAsk(args);
} catch (err) {
  if (err.name === 'ArgumentError' && err.message.includes('not a valid canonical model id')) {
    const stripped = String(args.model).replace(/^gemini-/, '');
    if (isVersionVariant(stripped)) return geminiAsk({ ...args, model: stripped });
  }
  throw err;
}

When it happens

Trigger: `--model 2.5_flash`, `--model 2.5-Flash`, `--model v2.5-flash`, `--model 2.5-flash-v2X`, or full SDK names like `--model gemini-2.5-flash` pasted from Google AI docs.

Common situations: Copy-pasting the full model string (`gemini-2.5-flash`) from Google documentation; typos or stray whitespace; using internal IDs with underscores instead of hyphens.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• --model requires a canonical model id (e.g. "2.5-flash"). Us
• --model "${value}" is not accepted. Short aliases like "pro"
• --thinking must be 'standard' or 'extended', got '${thinking
• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty

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