mudler/LocalAI · error · ValueError

Unknown Whisper model_ref={model_ref!r}; expected one of {li

Error message

Unknown Whisper model_ref={model_ref!r}; expected one of {list(MODEL_URLS)} or an openai/whisper-* HF id

What it means

The tinygrad Whisper wrapper recognizes aliases from the MODEL_URLS table (tiny..large style size names) or 'openai/whisper-*' HF ids; it also strips the 'openai/whisper-' prefix and tries a substring match of a known size name in the file basename as a fallback. Only when no known size matches does it raise ValueError listing the accepted aliases.

Source

Thrown at backend/python/tinygrad/backend.py:428

        Accepts a model-size alias (tiny / tiny.en / base / base.en / small /
        small.en) OR an explicit `.pt` file path OR the HF repo id naming
        convention `openai/whisper-*` (mapped to the matching OpenAI alias).
        """
        from vendor.whisper import init_whisper, MODEL_URLS

        alias = model_ref
        if "/" in alias and alias.startswith("openai/whisper-"):
            alias = alias.removeprefix("openai/whisper-")
        if alias not in MODEL_URLS:
            # Explicit path to a .pt checkpoint — fall back to size heuristic
            # via filename.
            basename = Path(alias).name.lower()
            for name in MODEL_URLS:
                if name in basename:
                    alias = name
                    break
            else:
                raise ValueError(
                    f"Unknown Whisper model_ref={model_ref!r}; expected one of {list(MODEL_URLS)} "
                    f"or an openai/whisper-* HF id"
                )

        model, enc = init_whisper(alias, batch_size=1)
        self.whisper_model = model
        self.whisper_tokenizer = enc

    # --------------------- LLM generation -------------------------------

    def _encode_prompt(self, prompt: str) -> list[int]:
        """Normalize tokenizer output: HF `tokenizers.Tokenizer.encode()`
        returns an `Encoding` with `.ids`; apps.llm's `SimpleTokenizer.encode()`
        returns `list[int]` directly."""
        encoded = self.llm_tokenizer.encode(prompt)
        return list(getattr(encoded, "ids", encoded))

    def _decode_tokens(self, ids: list[int]) -> str:

View on GitHub (pinned to 44413a9d06)

Solutions

1. Use one of the aliases listed in the error message (e.g. 'tiny', 'base', 'small', 'medium', 'large') or the 'openai/whisper-<size>' HF id form.
2. For a custom checkpoint, rename the file so it contains a recognized size token (e.g. mymodel-large.pt) so the filename heuristic matches.
3. Update the backend if the alias table is stale relative to the Whisper release you need.

Example fix

# before
model_ref = "whisper-turbo-neo"
# after
model_ref = "openai/whisper-large-v3"  # or a bare alias: "large"

KNOWN = {"tiny", "base", "small", "medium", "large"}  # keep in sync with MODEL_URLS

def whisper_ref_ok(ref: str) -> bool:
    a = ref.removeprefix("openai/whisper-")
    return a in KNOWN or any(k in Path(a).name.lower() for k in KNOWN)

try:
    self._load_whisper(ref)
except ValueError as e:
    if "Unknown Whisper" in str(e):
        raise ConfigError(f"bad whisper ref {ref!r}: use tiny|base|small|medium|large") from e
    raise

When it happens

Trigger: Calling Whisper with model_ref like 'whisper-turbo-neo', 'facebook/wav2vec2', or a .pt checkpoint whose filename contains no recognized size token (e.g. 'my_finetune.pt'); typo in the size name.

Common situations: Passing a non-OpenAI speech model id expecting generic HF support; custom fine-tuned checkpoints with arbitrary names; using 'whisper-large-v3-turbo' when the MODEL_URLS table predates that alias — filename fallback only works if a base alias like 'large' is a substring.

Related errors

• Model not found: {model_ref}
• No safetensors weights found under {model_dir}
• Expected HF model directory, got file: {model_path}
• config.json not found under {model_path}
• tokenizer.json not found under {model_dir}

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/c1a5f08658dd0c48. Report an issue: GitHub.