What causes "Error while downloading {image_url}." in mem0ai/mem0?

Fetch the URL yourself first (curl/requests) from the same machine to confirm reachability and status code

mem0ai/mem0 · error · Exception

Error while downloading {image_url}.

Error message

Error while downloading {image_url}.

What it means

Raised when get_image_description() throws while processing a valid-looking image_url part; mem0 wraps the original exception with 'Error while downloading {image_url}.' and chains it via `from e`. Despite the wording, the root cause (inspect e.__cause__) can be anything in the describe pipeline: an unreachable URL, a 403/404, an unsupported image format, a timeout, or a vision-LLM API failure — not only a download problem.

Source

Thrown at mem0/memory/utils.py:219

                ]
                if not text_parts:
                    continue
                returned_messages.append({"role": role, "content": " ".join(text_parts)})
            else:
                description = get_image_description(msg, llm, vision_details)
                returned_messages.append({"role": role, "content": description})
        elif isinstance(content, dict) and content.get("type") == "image_url":
            if llm is None:
                continue
            image_url_obj = content.get("image_url")
            image_url = image_url_obj.get("url") if isinstance(image_url_obj, dict) else None
            if not image_url:
                raise ValueError("image_url content part is missing image_url.url")
            try:
                description = get_image_description(image_url, llm, vision_details)
                returned_messages.append({"role": role, "content": description})
            except Exception as e:
                raise Exception(f"Error while downloading {image_url}.") from e
        else:
            # Regular text content
            returned_messages.append(msg)

    return returned_messages


def process_telemetry_filters(filters):
    """
    Process the telemetry filters
    """
    if filters is None:
        return [], {}

    encoded_ids = {}
    if "user_id" in filters:
        encoded_ids["user_id"] = hashlib.md5(filters["user_id"].encode()).hexdigest()
    if "agent_id" in filters:

View on GitHub (pinned to 001c235229)

Solutions

Fetch the URL yourself first (curl/requests) from the same machine to confirm reachability and status code
Inspect the chained exception (except Exception as e: print(e.__cause__)) to see whether it is download vs vision-LLM failure
Use long-lived accessible URLs or base64 data URIs; re-upload the image to storage you control
If it is the vision LLM failing, verify that model's API key, quota, and that the configured model supports vision

Example fix

# before
await memory.add([{"role": "user", "content": [{"type": "image_url", "image_url": {"url": signed_url}}]}], user_id="alice")

# after
import requests
assert requests.head(signed_url, timeout=10).status_code == 200, "URL expired; re-sign it"
await memory.add([{"role": "user", "content": [{"type": "image_url", "image_url": {"url": signed_url}}]}], user_id="alice")

Defensive patterns

Strategy: try-catch

Validate before calling

import requests
def url_ok(u, timeout=10) -> bool:
    try:
        return requests.head(u, timeout=timeout, allow_redirects=True).status_code < 400
    except requests.RequestException:
        return False
# skip or re-fetch images failing this check before memory.add()

Try / catch

try:
    await memory.add(messages, user_id=uid)
except Exception as e:
    if "Error while downloading" in str(e) and e.__cause__ is not None:
        logger.warning("image pipeline failed: %r", e.__cause__)
        # retry with the offending image part stripped, or with a fresh URL
    else:
        raise

Prevention

Pre-check image URLs (status + auth) from the same network as the mem0 process
Use long-lived URLs or data URIs you control
Log e.__cause__ — the wrapper message hides the real failure
Keep vision-LLM keys and quotas healthy; the wrap also covers provider errors

When it happens

Trigger: Passing an expired/signed S3 URL, a URL behind auth (403), a 404, or a URL unreachable from the server's network; passing a data: URI the vision provider rejects; vision LLM quota/API-key errors surfacing during description generation; slow hosts timing out during download.

Common situations: Pre-signed upload URLs that expired before the memory call; intranet image URLs used from a container without network access; free-tier vision API keys exhausted; oversized images rejected by the provider.

Related errors

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/c3fd7022de81d79c. Report an issue: GitHub.