PrefectHQ/fastmcp · error · ValueError

Either path or data must be provided

Error message

Either path or data must be provided

What it means

Image is a convenience wrapper around image bytes or a file path. Its constructor requires exactly one source: if both path and data are None there is nothing to encode, so it raises ValueError immediately. Construct it with either path= or data=, never neither.

Source

Thrown at fastmcp_slim/fastmcp/utilities/types.py:254

    if inspect.ismethod(fn):
        return types.MethodType(new_func, fn.__self__)
    else:
        return new_func


class Image:
    """Helper class for returning images from tools."""

    def __init__(
        self,
        path: str | Path | None = None,
        data: bytes | None = None,
        format: str | None = None,
        annotations: Annotations | None = None,
    ):
        if path is None and data is None:
            raise ValueError("Either path or data must be provided")
        if path is not None and data is not None:
            raise ValueError("Only one of path or data can be provided")

        self.path = self._get_expanded_path(path)
        self.data = data
        self._format = format
        self._mime_type = self._get_mime_type()
        self.annotations = annotations

    @staticmethod
    def _get_expanded_path(path: str | Path | None) -> Path | None:
        """Expand environment variables and user home in path."""
        return Path(os.path.expandvars(str(path))).expanduser() if path else None

    def _get_mime_type(self) -> str:
        """Get MIME type from format or guess from file extension."""
        if self._format:
            return f"image/{self._format.lower()}"

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass the file location: Image(path='img.png')
2. Pass raw bytes: Image(data=raw_bytes)
3. Guard the construction site so Image is only created when a source exists

Example fix

// before
img = Image()  # nothing provided
// after
img = Image(path='chart.png')  # or Image(data=open('chart.png','rb').read())

def make_image(path=None, data=None):
    if path is None and data is None:
        raise ValueError("image source required: pass path or data")
    return Image(path=path, data=data)

from typing import Optional
from pathlib import Path
def has_image_source(path: Optional[str], data: Optional[bytes]) -> bool:
    return path is not None or data is not None

try:
    img = Image(path=path)
except ValueError as e:
    logger.error("Cannot build Image: %s", e)
    return None

When it happens

Trigger: Image() with no arguments, Image(path=None, data=None), or passing the image source via a keyword the constructor does not accept (so both default to None).

Common situations: Dynamic code that builds an Image from optional user input where the variable is unset; refactors that renamed a variable but not the keyword; loading bytes conditionally and constructing Image unconditionally.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Only one of path or data can be provided
• Provided resource URI is invalid: {str(uri)!r}
• cache_ttl_seconds must be non-negative, got {ttl_seconds}
• max_cache_size must be non-negative, got {max_size}
• No image data available

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/73f59d4c1ddb63a0. Report an issue: GitHub.