What causes "audio input is not a readable staged file" in mudler/LocalAI?

Copy/upload the audio to a backend-visible location (shared volume) and pass that absolute path

mudler/LocalAI · error · ValueError

audio input is not a readable staged file

Error message

audio input is not a readable staged file

What it means

ValueError from _generate_avatar(): request.audio is set but os.path.isfile() fails, so the audio file is not present at that path on the backend host. Like start_image, audio is a staged-file reference, not inline data; the backend later loads it with librosa at 16 kHz mono.

Source

Thrown at backend/python/longcat-video/backend.py:613

            output = self.pipeline.generate_t2v(
                prompt=request.prompt,
                negative_prompt=negative_prompt,
                height=height,
                width=width,
                num_frames=frames,
                num_inference_steps=steps,
                use_distill=use_distill,
                guidance_scale=guidance_scale,
                generator=generator,
            )[0]

        self._save_video(output, request.dst, fps)

    def _generate_avatar(self, request, params, context):
        if not request.audio:
            raise ValueError("audio is required for LongCat-Video-Avatar-1.5")
        if not os.path.isfile(request.audio):
            raise ValueError("audio input is not a readable staged file")

        use_distill = self.options["use_distill"]
        steps = (
            8
            if use_distill
            else require_int(
                request.step or 50,
                "step",
                minimum=1,
                maximum=200,
            )
        )
        text_guidance = (
            1.0
            if use_distill
            else require_float(
                request.cfg_scale or 4.0,
                "cfg_scale",

View on GitHub (pinned to 44413a9d06)

Solutions

Copy/upload the audio to a backend-visible location (shared volume) and pass that absolute path
Confirm the file still exists at request time and the backend process has read permission
Prefer wav/mp3 files librosa/ffmpeg can decode

Example fix

# before
req.audio = "/tmp/client/voice.wav"

# after
req.audio = "/data/staged/voice.wav"  # mounted into the backend container

Defensive patterns

Strategy: validation

Validate before calling

import os

def validate_staged_audio(audio_path: str) -> str:
    if not audio_path or not os.path.isfile(audio_path):
        raise FileNotFoundError(f"audio not staged on backend: {audio_path!r}")
    if os.path.getsize(audio_path) == 0:
        raise ValueError(f"audio file is empty: {audio_path}")
    return audio_path

Try / catch

try:
    stub.GenerateVideo(req)
except grpc.RpcError as e:
    if "not a readable staged file" in (e.details() or ""):
        req.audio = stage_file(req.audio, STAGING_DIR)  # re-stage and retry once
        stub.GenerateVideo(req)
    else:
        raise

Prevention

Use a shared staging volume and verify readability from the backend side before each request
Include file existence checks in request-building helpers

When it happens

Trigger: Passing a client-local path never copied to the backend; stale path after the staged file was cleaned up; container path mismatch (file mounted at a different location inside the backend container).

Common situations: Distributed setup where the API gateway and the GPU backend do not share a filesystem; temp-file race where the audio is deleted before the request is processed.

Related errors

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