openai/whisper · error · ValueError

model should be one of {available_models()} or path to a mod

Error message

model should be one of {available_models()} or path to a model checkpoint

What it means

The whisper CLI registers --model with type=valid_model_name, an argparse type callable that accepts the value only if it is in whisper.available_models() or an existing filesystem path (os.path.exists, note: not isfile). argparse wraps the ValueError into 'invalid valid_model_name value' and exits before any transcription.

Source

Thrown at whisper/transcribe.py:523

                prompt_reset_since = len(all_tokens)

            # update progress bar
            pbar.update(min(content_frames, seek) - previous_seek)

    return dict(
        text=tokenizer.decode(all_tokens[len(initial_prompt_tokens) :]),
        segments=all_segments,
        language=language,
    )


def cli():
    from . import available_models

    def valid_model_name(name):
        if name in available_models() or os.path.exists(name):
            return name
        raise ValueError(
            f"model should be one of {available_models()} or path to a model checkpoint"
        )

    # fmt: off
    parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter)
    parser.add_argument("audio", nargs="+", type=str, help="audio file(s) to transcribe")
    parser.add_argument("--model", default="turbo", type=valid_model_name, help="name of the Whisper model to use")
    parser.add_argument("--model_dir", type=str, default=None, help="the path to save model files; uses ~/.cache/whisper by default")
    parser.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu", help="device to use for PyTorch inference")
    parser.add_argument("--output_dir", "-o", type=str, default=".", help="directory to save the outputs")
    parser.add_argument("--output_format", "-f", type=str, default="all", choices=["txt", "vtt", "srt", "tsv", "json", "jsonl", "all"], help="format of the output file; if not specified, all available formats will be produced")
    parser.add_argument("--verbose", type=str2bool, default=True, help="whether to print out the progress and debug messages")

    parser.add_argument("--task", type=str, default="transcribe", choices=["transcribe", "translate"], help="whether to perform X->X speech recognition ('transcribe') or X->English translation ('translate')")
    parser.add_argument("--language", type=str, default=None, choices=sorted(LANGUAGES.keys()) + sorted([k.title() for k in TO_LANGUAGE_CODE.keys()]), help="language spoken in the audio, specify None to perform language detection")

    parser.add_argument("--temperature", type=float, default=0, help="temperature to use for sampling")
    parser.add_argument("--best_of", type=optional_int, default=5, help="number of candidates when sampling with non-zero temperature")

View on GitHub (pinned to 5f86d1d863)

Solutions

1. List valid names: python -m whisper --help or python -c "import whisper; print(whisper.available_models())"
2. Use an absolute path for local checkpoints: --model $PWD/models/finetuned.pt
3. Fix the typo (dot for .en variants: base.en) and re-run

Example fix

# before
whisper audio.mp3 --model medium-en  # argparse error: invalid valid_model_name value

# after
whisper audio.mp3 --model medium.en
# or a real checkpoint path:
whisper audio.mp3 --model /abs/path/finetuned.pt

import os, whisper

def valid_cli_model(name: str) -> str:
    if name in whisper.available_models() or os.path.exists(os.path.abspath(name)):
        return name
    raise ValueError(f"model must be one of {whisper.available_models()} or an existing path")

When it happens

Trigger: whisper audio.mp3 --model large (older name no longer in _MODELS) or --model ./models/finetuned.pt when the path does not exist from the current directory; any typo triggers it at argument-parsing time.

Common situations: Scripts written against older/newer whisper versions where the model list changed (e.g. 'large-v3-turbo' vs 'turbo'); relative checkpoint paths run from a different CWD (cron, systemd services); CI invoking the CLI with a model path that was never downloaded into the image.

Related errors

• Model {name} not found; available models = {available_models
• Expected one of {set(str2val.keys())}, got {string}
• {download_target} exists and is not a regular file
• Language {language} not found in tokenizer.
• Unsupported language: {language}

AI-assisted analysis of openai/whisper@5f86d1d863 (2026-08-14). Data as JSON: /api/errors/90d75744d3695dea. Report an issue: GitHub.