mem0ai/mem0 · error · NetworkError

NET_TIMEOUT

NET_TIMEOUT

Error message

Request timed out: {str(e)}

What it means

This is the client-side translation of an httpx.TimeoutException into Mem0's structured NetworkError with error_code NET_TIMEOUT. The api_error_handler decorator catches transport-level exceptions from requests and re-raises them as NetworkError with a suggestion and debug_info. The message embeds the underlying httpx exception string.

Source

Thrown at mem0/client/utils.py:72

        for header in ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"]:
            value = e.response.headers.get(header)
            if value:
                debug_info[header.lower().replace("-", "_")] = value

    raise create_exception_from_response(
        status_code=e.response.status_code,
        response_text=response_text,
        details=error_details,
        debug_info=debug_info,
    )


def _handle_request_error(e):
    logger.error(f"Request error occurred: {e}")

    if isinstance(e, httpx.TimeoutException):
        raise NetworkError(
            message=f"Request timed out: {str(e)}",
            error_code="NET_TIMEOUT",
            suggestion="Please check your internet connection and try again",
            debug_info={"error_type": "timeout", "original_error": str(e)},
        )
    elif isinstance(e, httpx.ConnectError):
        raise NetworkError(
            message=f"Connection failed: {str(e)}",
            error_code="NET_CONNECT",
            suggestion="Please check your internet connection and try again",
            debug_info={"error_type": "connection", "original_error": str(e)},
        )
    else:
        raise NetworkError(
            message=f"Network request failed: {str(e)}",
            error_code="NET_GENERIC",
            suggestion="Please check your internet connection and try again",
            debug_info={"error_type": "request", "original_error": str(e)},

View on GitHub (pinned to 001c235229)

Solutions

1. Retry the request — timeouts are often transient (ideally with backoff, and make add() idempotent via run_id/agent_id scoping)
2. Increase the client timeout passed to MemoryClient (e.g. timeout=60) if you regularly do large batch calls
3. Split oversized batch payloads into smaller chunks
4. Check local network/proxy/VPN conditions if timeouts are persistent

Example fix

# before
result = client.add(messages, user_id="alice")  # large batch times out

# after
client = MemoryClient(api_key=API_KEY, timeout=60)
for chunk in [messages[i:i+100] for i in range(0, len(messages), 100)]:
    client.add(chunk, user_id="alice")

# Pre-flight sanity (does not guarantee no timeout, but catches obvious issues)
import socket, time
socket.setdefaulttimeout(5)
t0 = time.time()
try:
    socket.getaddrinfo("api.mem0.ai", 443)
except OSError:
    raise RuntimeError("no DNS/egress; fix network before retrying API calls")

from mem0.exceptions import NetworkError

def is_timeout(err: NetworkError) -> bool:
    return getattr(err, "error_code", None) == "NET_TIMEOUT"

from mem0.exceptions import NetworkError

for attempt in range(3):
    try:
        result = client.add(messages, user_id=uid)
        break
    except NetworkError as e:
        if e.error_code != "NET_TIMEOUT" or attempt == 2:
            raise
        time.sleep(2 ** attempt)

When it happens

Trigger: Any decorated HTTP call (memory add/search/get, project ops) where the HTTP operation exceeds httpx's timeout — default is 5s connect/read in many clients; large batch adds and slow embedding pipelines are typical. httpx.TimeoutException subclasses include ConnectTimeout, ReadTimeout, WriteTimeout, PoolTimeout.

Common situations: Bulk-ingesting thousands of memories in one call; slow network or VPN/proxy adding latency; the Mem0 platform briefly slow; timeouts set too low for heavy vector-store workloads.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• NET_GENERIC
• NET_CONNECT
• HTTP ${resp.status}: ${detail}
• Invalid response format from ping endpoint
• Failed to ping server: ${error.message || "Unknown error"}

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