agentscope-ai/agentscope · error · RuntimeError

Failed to fetch bytes from URL `{url}` after {max_retries} r

Error message

Failed to fetch bytes from URL `{url}` after {max_retries} retries.

What it means

agentscope downloads remote resources (images, audio, files) referenced by URL via _get_bytes_from_web_url. It retries the HTTP request up to max_retries times and, if all attempts fail (connection error, timeout, non-success status), raises this RuntimeError naming the URL and retry count.

Source

Thrown at src/agentscope/_utils/_common.py:250

    import requests

    for _ in range(max_retries):
        try:
            response = requests.get(url)
            response.raise_for_status()
            return response.content.decode("utf-8")

        except UnicodeDecodeError:
            return base64.b64encode(response.content).decode("ascii")

        except Exception as e:
            logger.info(
                "Failed to fetch bytes from URL %s. Error %s. Retrying...",
                url,
                str(e),
            )

    raise RuntimeError(
        f"Failed to fetch bytes from URL `{url}` after {max_retries} retries.",
    )


def _map_text_to_uuid(text: str) -> str:
    """Map the given text to a deterministic UUID string.

    Args:
        text (`str`):
            The input text to be mapped to a UUID.

    Returns:
        `str`:
            A deterministic UUID string derived from the input text.
    """
    return str(uuid.uuid3(uuid.NAMESPACE_DNS, text))

View on GitHub (pinned to e90f1c7592)

Solutions

  1. Verify the URL is reachable (curl -I <url>) from the same environment
  2. If behind a proxy, set HTTP_PROXY/HTTPS_PROXY environment variables
  3. Increase max_retries for flaky endpoints, or add your own retry/backoff around the call
  4. If the resource is local, pass local file bytes instead of a URL; for authenticated resources, download with headers yourself and pass the bytes

Example fix

# before
block = ImageBlock(url="https://example.com/pic.png")  # host unreachable

# after
import requests
resp = requests.get("https://example.com/pic.png", headers={"Authorization": "Bearer ..."}, timeout=30)
resp.raise_for_status()
block = ImageBlock(bytes=resp.content)  # pass bytes directly
Defensive patterns

Strategy: retry

Validate before calling

import requests

def url_is_fetchable(url: str, timeout: float = 10.0) -> bool:
    try:
        r = requests.head(url, timeout=timeout, allow_redirects=True)
        return r.status_code < 400
    except requests.RequestException:
        return False

if not url_is_fetchable(url):
    # serve local bytes or fail gracefully instead of letting the library raise

Type guard

from urllib.parse import urlparse
from typing import TypeGuard

def is_http_url(v: str) -> TypeGuard[str]:
    try:
        p = urlparse(v)
        return p.scheme in ("http", "https") and bool(p.netloc)
    except ValueError:
        return False

Try / catch

try:
    block = ImageBlock(url=url)
    ...  # downstream processing
except RuntimeError as e:
    if "Failed to fetch bytes" in str(e):
        # exponential backoff retry, then fall back to local file
        for attempt in range(5):
            try:
                break
            except RuntimeError:
                time.sleep(2 ** attempt)
        else:
            block = ImageBlock(bytes=local_fallback_bytes)
    else:
        raise

Prevention

When it happens

Trigger: Passing a URL block (e.g. an image or audio block with a URL) where the host is unreachable, returns 404/403/5xx, DNS fails, or the process has no network egress. Every retry must fail; transient failures usually succeed on retry.

Common situations: Offline or sandboxed environments without internet, expired/signed S3 URLs, hotlinking-protected URLs requiring headers, typos in URLs, corporate proxies not configured, or remote endpoints with transient 503s exceeding the retry budget.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/68b411a0688736a4. Report an issue: GitHub.