{"record":{"id":"3cb2fe419a63ba93","repo":"mudler/LocalAI","slug":"start-image-is-not-a-readable-staged-file","errorCode":null,"errorMessage":"start_image is not a readable staged file","messagePattern":"start_image is not a readable staged file","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/python/longcat-video/backend.py","lineNumber":271,"sourceCode":"            if not request_state[\"finished\"] and self.pipeline is not None:\n                self.pipeline._interrupt = True\n\n        try:\n            params, ignored_params = select_known_options(\n                dict(request.params), REQUEST_PARAMS\n            )\n            if ignored_params:\n                print(\n                    f\"longcat-video ignoring unknown request param(s): {', '.join(ignored_params)}\",\n                    file=sys.stderr,\n                )\n\n            os.makedirs(os.path.dirname(request.dst) or \".\", mode=0o750, exist_ok=True)\n            if hasattr(context, \"add_callback\"):\n                context.add_callback(interrupt_if_cancelled)\n\n            if request.start_image and not os.path.isfile(request.start_image):\n                raise ValueError(\"start_image is not a readable staged file\")\n            if request.num_frames < 0:\n                raise ValueError(\"num_frames must not be negative\")\n\n            if self.model_kind == MODEL_KIND_BASE:\n                if request.audio:\n                    raise ValueError(\n                        \"audio input requires a LongCat-Video-Avatar-1.5 model\"\n                    )\n                self._generate_base(request, params)\n            else:\n                self._generate_avatar(request, params, context)\n\n            return backend_pb2.Result(\n                message=\"Video generated successfully\", success=True\n            )\n        except ValueError as err:\n            return self._fail(context, grpc.StatusCode.INVALID_ARGUMENT, str(err))\n        except Exception as err:","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/longcat-video/backend.py#L253-L289","documentation":"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.","triggerScenarios":"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.","commonSituations":"Running client and backend on different machines/containers without a shared volume; assuming the API accepts base64 image data in start_image.","solutions":["Stage (copy) the image to a path accessible to the backend process, then pass that absolute path in start_image","Verify the path exists from the backend's perspective (shared volume mount, correct container path)","If you do not need image conditioning, leave start_image empty"],"exampleFix":"# before\nreq.start_image = \"/home/me/local/photo.png\"  # client-only path\n\n# after\n# copy photo.png into the volume shared with the backend, then:\nreq.start_image = \"/data/staged/photo.png\"","handlingStrategy":"validation","validationCode":"import os\n\ndef stage_file(local_path: str, staged_dir: str) -> str:\n    \"\"\"Copy a client-side file into the backend-visible staging dir; return staged path.\"\"\"\n    os.makedirs(staged_dir, exist_ok=True)\n    dst = os.path.join(staged_dir, os.path.basename(local_path))\n    shutil.copy2(local_path, dst)\n    assert os.path.isfile(dst)\n    return dst\n\nrequest.start_image = stage_file(\"/home/me/photo.png\", \"/data/staged\")","typeGuard":null,"tryCatchPattern":"try:\n    stub.VideoRequestSend(request)\nexcept grpc.RpcError as e:\n    if \"start_image\" in (e.details() or \"\"):\n        request.start_image = stage_and_verify(request.start_image)\n        stub.VideoRequestSend(request)\n    else:\n        raise","preventionTips":["Never pass client-local absolute paths across machine boundaries; always stage to a shared volume","Verify staged files with os.path.isfile from the backend's environment before sending the request"],"tags":["python","longcat-video","grpc","file-handling","validation"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}