#950·mlx-audio

Whisper checkpoints without a HF processor (e.g. mlx-community/whisper-large-v3-turbo-8bit, converted with mlx-audio-plus) fail late with a confusing "Processor not found" error instead of a clear load-time message

Author: DroppixCreated Sep 7, 2026Updated Sep 7, 2026

Description

Loading mlx-community/whisper-large-v3-turbo-8bit and then transcribing fails with:

ValueError: Processor not found. Make sure the model was loaded with a HuggingFace processor.

This repo was converted with a different, unrelated fork - mlx-audio-plus by DePasqualeOrg (confirmed in the repo's own model card: library_name: mlx-audio-plus) - not this project. It only ships config.json, model.safetensors, and multilingual.tiktoken; no preprocessor_config.json or HF tokenizer files, because mlx-audio-plus loads Whisper differently.

In this repo's loader (mlx_audio/stt/models/whisper/whisper.py), the failure is caught and silently downgraded to a warning at load time:

python
try:
    from transformers import WhisperProcessor
    processor = WhisperProcessor.from_pretrained(str(model_path))
    model._processor = processor
except Exception as e:
    model._processor = None
    warnings.warn(f"Could not load WhisperProcessor: {e}.")

The actual hard failure only surfaces much later, on the first transcription call, in get_tokenizer():

python
if hasattr(self, "_processor") and self._processor is not None:
    ...
else:
    raise ValueError(
        "Processor not found. Make sure the model was loaded with a HuggingFace processor."
    )

Since mlx-community hosts Whisper conversions for both this project and for unrelated forks under the same org namespace, it's easy to pick an incompatible checkpoint by mistake and get no useful signal until a transcription request fails at request time (in server contexts like mlx-vlm, this surfaces as an opaque 500 with no indication of why).

Reproduction

python
from mlx_audio.stt.utils import load

model = load("mlx-community/whisper-large-v3-turbo-8bit")
result = model.generate("audio.wav")  # raises ValueError: Processor not found...

Also reproducible through mlx-vlm's /v1/audio/transcriptions route, which loads this exact checkpoint.

Suggested fix

  • Raise (or at least log at error/warning visibility with the model id) at load time when WhisperProcessor.from_pretrained fails, rather than deferring to a ValueError on first use - ideally with a message pointing out that the checkpoint may have been converted for a different library.
  • Optionally: inspect the checkpoint's config.json/model card library_name at load time and warn explicitly when it doesn't match mlx-audio, since that's the actual root cause here.

Environment

  • mlx-audio (via mlx-vlm server / Nativ)
  • Model: mlx-community/whisper-large-v3-turbo-8bit