mudler/LocalAI · error · ValueError

start_image is not a readable staged file

Error message

start_image is not a readable staged file

What it means

ValueError from longcat-video's video generation RPC: the request's start_image field names a file that does not exist on disk (os.path.isfile fails). Backends receive staged local file paths, not blobs, so the image must have been copied to the backend's filesystem before the request. The error surfaces as gRPC INVALID_ARGUMENT via the surrounding except ValueError handler.

Source

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

            if not request_state["finished"] and self.pipeline is not None:
                self.pipeline._interrupt = True

        try:
            params, ignored_params = select_known_options(
                dict(request.params), REQUEST_PARAMS
            )
            if ignored_params:
                print(
                    f"longcat-video ignoring unknown request param(s): {', '.join(ignored_params)}",
                    file=sys.stderr,
                )

            os.makedirs(os.path.dirname(request.dst) or ".", mode=0o750, exist_ok=True)
            if hasattr(context, "add_callback"):
                context.add_callback(interrupt_if_cancelled)

            if request.start_image and not os.path.isfile(request.start_image):
                raise ValueError("start_image is not a readable staged file")
            if request.num_frames < 0:
                raise ValueError("num_frames must not be negative")

            if self.model_kind == MODEL_KIND_BASE:
                if request.audio:
                    raise ValueError(
                        "audio input requires a LongCat-Video-Avatar-1.5 model"
                    )
                self._generate_base(request, params)
            else:
                self._generate_avatar(request, params, context)

            return backend_pb2.Result(
                message="Video generated successfully", success=True
            )
        except ValueError as err:
            return self._fail(context, grpc.StatusCode.INVALID_ARGUMENT, str(err))
        except Exception as err:

View on GitHub (pinned to 44413a9d06)

Solutions

1. Stage (copy) the image to a path accessible to the backend process, then pass that absolute path in start_image
2. Verify the path exists from the backend's perspective (shared volume mount, correct container path)
3. If you do not need image conditioning, leave start_image empty

Example fix

# before
req.start_image = "/home/me/local/photo.png"  # client-only path

# after
# copy photo.png into the volume shared with the backend, then:
req.start_image = "/data/staged/photo.png"

import os

def stage_file(local_path: str, staged_dir: str) -> str:
    """Copy a client-side file into the backend-visible staging dir; return staged path."""
    os.makedirs(staged_dir, exist_ok=True)
    dst = os.path.join(staged_dir, os.path.basename(local_path))
    shutil.copy2(local_path, dst)
    assert os.path.isfile(dst)
    return dst

request.start_image = stage_file("/home/me/photo.png", "/data/staged")

try:
    stub.VideoRequestSend(request)
except grpc.RpcError as e:
    if "start_image" in (e.details() or ""):
        request.start_image = stage_and_verify(request.start_image)
        stub.VideoRequestSend(request)
    else:
        raise

When it happens

Trigger: Passing a client-side path like /home/user/img.png that was never uploaded/staged to the backend host; relative path resolved against the backend process cwd that does not exist; file deleted between staging and request.

Common situations: Running client and backend on different machines/containers without a shared volume; assuming the API accepts base64 image data in start_image.

Related errors

• num_frames must not be negative
• audio input requires a LongCat-Video-Avatar-1.5 model
• audio is required for LongCat-Video-Avatar-1.5
• audio input is not a readable staged file
• audio contains no samples

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