mudler/LocalAI · error · ValueError

Unknown Whisper model_ref=

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.

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

• config.json not found under
• Expected HF model directory, got file
• Inline reward function
• Model not found
• No safetensors weights found under

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

Appendix: 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)