rohitg00/ai-engineering-from-scratch · error · ValueError

image_bytes must not be empty

Error message

image_bytes must not be empty

What it means

Raised by build_multimodal_request when image_bytes is empty. An image content block requires actual bytes; an empty payload would produce a request the real API rejects, so the builder fails fast offline (multimodal_lab_fixture).

Source

Thrown at certifications/claude/lessons/08-messages-api-and-application-lifecycle/code/main.py:198

        raise ValueError("batch size must be positive")
    return [items[index : index + size] for index in range(0, len(items), size)]


def stable_cache_key(model: str, stable_prefix: str) -> str:
    payload = f"{model}\0{stable_prefix}".encode("utf-8")
    return hashlib.sha256(payload).hexdigest()


IMAGE_MEDIA_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp"}
DOCUMENT_MEDIA_TYPES = {"application/pdf", "text/plain"}


def build_multimodal_request(prompt: str, image_bytes: bytes, reusable_file_id: str) -> dict[str, Any]:
    """Build an offline request body with inline vision and a reusable file asset."""
    if not prompt.strip():
        raise ValueError("prompt must not be empty")
    if not image_bytes:
        raise ValueError("image_bytes must not be empty")
    if not reusable_file_id.strip():
        raise ValueError("reusable_file_id must not be empty")
    return {
        "model": "<current-model-id>",
        "max_tokens": 400,
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": prompt},
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": "image/png",
                            "data": base64.b64encode(image_bytes).decode("ascii"),
                        },
                    },

View on GitHub (pinned to 39ea8a1c6d)

Solutions

1. Verify the file size is greater than 0 before reading or calling
2. Check the upstream fetch returned a non-empty body and raise on empty
3. Log byte counts when ingesting images to catch empty captures early

Example fix

# before
data = path.read_bytes()  # 0-byte file slips through
build_multimodal_request(prompt, data, file_id)
# after
data = path.read_bytes()
if not data:
    raise ValueError(f"empty image file: {path}")
build_multimodal_request(prompt, data, file_id)

if not image_bytes:
    raise ValueError("image file is empty")
req = build_multimodal_request(prompt, image_bytes, file_id)

When it happens

Trigger: Calling build_multimodal_request('prompt', b'', 'file_1') after a file read returned empty bytes or a download saved nothing.

Common situations: Reading a 0-byte file, a failed upload/download that returns empty bytes without raising, or a test fixture reading the wrong path.

Related errors

• prompt must not be empty
• reusable_file_id must not be empty
• tool_use requires name and object input
• response content must be a non-empty block list
• every content block needs a type

AI-assisted analysis of rohitg00/ai-engineering-from-scratch@39ea8a1c6d (2026-08-26). Data as JSON: /api/errors/460c9efaa2f91504. Report an issue: GitHub.