{"record":{"id":"ecfe80797fbbde8c","repo":"crewAIInc/crewAI","slug":"image-file-does-not-exist-v","errorCode":null,"errorMessage":"Image file does not exist: {v}","messagePattern":"Image file does not exist: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/vision_tool/vision_tool.py","lineNumber":26,"sourceCode":"from pydantic import BaseModel, Field, PrivateAttr, field_validator\n\nfrom crewai_tools.security.safe_path import validate_file_path\n\n\nclass ImagePromptSchema(BaseModel):\n    \"\"\"Input for Vision Tool.\"\"\"\n\n    image_path_url: str = \"The image path or URL.\"\n\n    @field_validator(\"image_path_url\")\n    @classmethod\n    def validate_image_path_url(cls, v: str) -> str:\n        if v.startswith(\"http\"):\n            return v\n\n        path = Path(v)\n        if not path.exists():\n            raise ValueError(f\"Image file does not exist: {v}\")\n\n        valid_extensions = {\".jpg\", \".jpeg\", \".png\", \".gif\", \".webp\"}\n        if path.suffix.lower() not in valid_extensions:\n            raise ValueError(\n                f\"Unsupported image format. Supported formats: {valid_extensions}\"\n            )\n\n        return v\n\n\nclass VisionTool(BaseTool):\n    \"\"\"Tool for analyzing images using vision models.\n\n    Args:\n        llm: Optional LLM instance to use\n        model: Model identifier to use if no LLM is provided\n    \"\"\"\n","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/vision_tool/vision_tool.py#L8-L44","documentation":"VisionTool's Pydantic input schema validates image_path_url. For non-http inputs it converts the string to a Path and checks existence; if the file is not on disk at validation time (i.e., when the tool is invoked), ValueError is raised naming the missing path.","triggerScenarios":"Calling VisionTool.run(image_path_url='./photo.png') with a relative or absolute path that does not exist relative to the process's current working directory, or a local path while the file lives on another machine/container.","commonSituations":"Agents hallucinating or typo-ing file paths; relative paths breaking when the worker process has a different CWD (containers, notebooks, cron); files not yet written before the tool call; running in Docker without mounting the image directory.","solutions":["Verify the path before invoking: expand and resolve it with pathlib and check .exists().","Use absolute paths (str(Path(p).resolve())) so CWD differences cannot break resolution.","Mount/copy the image into the container or working directory it runs in.","If the image is remote, pass a full http(s) URL instead, which skips the file check."],"exampleFix":"# before\nVisionTool().run(image_path_url='images/cat.jpg')  # CWD mismatch -> ValueError\n\n# after\nfrom pathlib import Path\np = Path('images/cat.jpg').resolve()\nassert p.exists(), f'missing image: {p}'\nVisionTool().run(image_path_url=str(p))","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef resolve_image(p: str) -> str:\n    if p.startswith('http'):\n        return p\n    path = Path(p).expanduser().resolve()\n    if not path.is_file():\n        raise FileNotFoundError(f'image not found: {path}')\n    return str(path)\n\n# image_path_url = resolve_image(raw_path) before calling VisionTool","typeGuard":"from pathlib import Path\n\ndef is_local_image(v: str) -> bool:\n    if v.startswith('http'):\n        return False\n    p = Path(v).expanduser().resolve()\n    return p.is_file() and p.suffix.lower() in {'.jpg', '.jpeg', '.png', '.gif', '.webp'}","tryCatchPattern":"try:\n    VisionTool().run(image_path_url=path)\nexcept ValueError as e:\n    if 'does not exist' in str(e):\n        path = str(Path(path).resolve())  # fix CWD-relative path, retry once\n        VisionTool().run(image_path_url=path)\n    else:\n        raise","preventionTips":["Always pass absolute, resolved paths to VisionTool.","Validate file existence and extension before the tool call (mirror the tool's own checks).","Mount image directories into containers; never assume the tool's CWD matches yours."],"tags":["validation","file-path","vision","pydantic"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}