NousResearch/hermes-agent · warning · ValueError

Image at {url} exceeds {max_bytes // (1024 * 1024)}MB cap; r

Error message

Image at {url} exceeds {max_bytes // (1024 * 1024)}MB cap; refusing to cache.

What it means

While downloading an image to cache, the streamed body exceeded max_bytes before completion (bytes_written > max_bytes after a 64KB chunk). The partially-written file is closed and unlinked, and this ValueError refuses to cache the oversized image — a resource-exhaustion guard in agent/image_gen_provider.py so a hostile or misbehaving URL cannot fill the disk.

Source

Thrown at agent/image_gen_provider.py:332

        extension = "png"

    ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
    short = uuid.uuid4().hex[:8]
    path = _images_cache_dir() / f"{prefix}_{ts}_{short}.{extension}"

    bytes_written = 0
    with path.open("wb") as fh:
        for chunk in response.iter_content(chunk_size=64 * 1024):
            if not chunk:
                continue
            bytes_written += len(chunk)
            if bytes_written > max_bytes:
                fh.close()
                try:
                    path.unlink()
                except OSError:
                    pass
                raise ValueError(
                    f"Image at {url} exceeds {max_bytes // (1024 * 1024)}MB cap; refusing to cache."
                )
            fh.write(chunk)

    if bytes_written == 0:
        try:
            path.unlink()
        except OSError:
            pass
        raise ValueError(f"Image at {url} returned 0 bytes; refusing to cache.")

    return path


def success_response(
    *,
    image: str,
    model: str,

View on GitHub (pinned to c896c09c42)

Solutions

1. Regenerate at a smaller resolution / lower quality so the output fits under the cap.
2. Raise the cache size cap in the image-gen provider configuration if the cap is set below legitimate output sizes.
3. Verify the URL actually returns the intended image (curl -I) — oversized responses often mean a wrong content type.
4. Host oversized artifacts externally and pass a link instead of caching them.

Example fix

# before — provider emits 20MB PNG, cap is 10MB
image = provider.generate(prompt="...", size="2048x2048")
# after — smaller render fits the cap
image = provider.generate(prompt="...", size="1024x1024")

import urllib.request

def image_within_cap(url: str, max_bytes: int) -> bool:
    size = int(urllib.request.urlopen(urllib.request.Request(
        url, method='HEAD')).headers.get('Content-Length') or 0)
    return 0 < size <= max_bytes  # note: enforcement is per-chunk, headers can lie

try:
    path = cache_image(url, max_bytes=max_bytes)
except ValueError as e:
    if 'exceeds' in str(e) and 'cap' in str(e):
        # regenerate smaller or raise the configured cap; partial file is auto-removed
        ...

When it happens

Trigger: Downloading from a URL whose Content-Length/body exceeds the configured cap (max_bytes, reported in the message as MB) — enforced incrementally per chunk, so it triggers even when the header understates the size.

Common situations: Image-generation provider returning unexpectedly large outputs; a URL returning a video or archive instead of an image; max_bytes configured too small for legitimately high-resolution renders.

Related errors

• Video at {url} exceeds {max_bytes // (1024 * 1024)}MB cap; r
• Content too large
• Could not fetch image: ${response.status}
• image too large (max ${mb} MB)
• Checksum mismatch for {asset_name}: expected {expected}, got

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/5dc7b2459360530f. Report an issue: GitHub.