JuliusBrussee/caveman · error · MiddlewareError

remote_content_not_enabled

remote_content_not_enabled

Error message

remote_content_not_enabled

What it means

For non-local (remote) endpoints the runtime requires allow_remote_content=True AND an https scheme; otherwise it raises MiddlewareError("remote_content_not_enabled"). This is a safety guard preventing original prompt/response content from traveling to remote hosts unencrypted or without explicit opt-in.

Solutions

  1. Set allow_remote_content=True and use an https:// endpoint
  2. For local development, keep the endpoint on 127.0.0.1/localhost (http is allowed for local hosts)
  3. If TLS terminates at a proxy, use https end-to-end or run the runtime locally
  4. Catch MiddlewareError("remote_content_not_enabled") in bootstrap code to surface the misconfiguration clearly

Example fix

// before
Runtime(endpoint="http://proxy.example.com")  # remote + http
// after
Runtime(endpoint="https://proxy.example.com", allow_remote_content=True)
Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlsplit
def remote_endpoint_ready(endpoint: str, allow_remote_content: bool) -> bool:
    u = urlsplit(endpoint)
    local = u.hostname in ('127.0.0.1', '::1', 'localhost')
    return local or (allow_remote_content and u.scheme == 'https')

Try / catch

try:
    runtime = Runtime(endpoint=ep, allow_remote_content=allow_remote)
except MiddlewareError as e:
    if str(e) == 'remote_content_not_enabled':
        raise ConfigError('remote endpoints require allow_remote_content=True and https') from e
    raise

Prevention

When it happens

Trigger: Constructing the runtime with a remote hostname (not 127.0.0.1/::1/localhost) while either allow_remote_content is left at its default False, or the endpoint uses plain http.

Common situations: Pointing the middleware at a staging/production proxy over http; forgetting the allow_remote_content flag when moving from local dev to a remote gateway; TLS terminated in front so the app uses http internally.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/74d5fded18a21b64. Report an issue: GitHub.

Appendix: source

Thrown at packages/sdk/python/caveman_cloud/middleware/runtime.py:69

                           caps.get("policy_revision"), caps.get("persistent"), caps.get("recovery"), PREFLIGHT_ACTIONS[reason])


def _json(value: Any) -> str:
    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), allow_nan=False)


class MiddlewareRuntime:
    def __init__(self, *, endpoint: str = "http://127.0.0.1:8787", token: str | None = None,
                 allow_remote_content: bool = False, mode: str = "compress", deadline_ms: int = 100,
                 retrieve_deadline_ms: int = 5000,
                 strict: bool = False, on_diagnostic: Callable[[dict], None] | None = None,
                 on_report: Callable[[CallReport], None] | None = None):
        url = urlsplit(endpoint)
        local = url.hostname in ("127.0.0.1", "::1", "localhost")
        if url.scheme not in ("http", "https") or not url.hostname or url.username or url.password or url.query or url.fragment or url.path not in ("", "/"):
            raise MiddlewareError("invalid_endpoint")
        if not local and (not allow_remote_content or url.scheme != "https"):
            raise MiddlewareError("remote_content_not_enabled")
        if type(deadline_ms) is not int or deadline_ms <= 0 or mode not in ("off", "record", "compress"):
            raise MiddlewareError("invalid_configuration")
        # A model asking to see an original is waiting on a page of stored text,
        # not on the optimizer in front of a provider call. Separate budget.
        if type(retrieve_deadline_ms) is not int or retrieve_deadline_ms <= 0:
            raise MiddlewareError("invalid_configuration")
        self.endpoint = f"{url.scheme}://{url.netloc}"
        self.mode, self.deadline_ms, self.strict = mode, deadline_ms, strict
        self.retrieve_deadline_ms = retrieve_deadline_ms
        self._token, self._diagnostic = token, on_diagnostic
        self._report_sink, self._last_report = on_report, None
        self._url = url
        self._connections: set[http.client.HTTPConnection] = set()
        self._caps: dict | None = None
        self._bindings: weakref.WeakKeyDictionary[RecoveryBinding, tuple] = weakref.WeakKeyDictionary()
        self._lock = threading.RLock()
        self._slots = threading.BoundedSemaphore(16)
        self._closed = False

View on GitHub (pinned to 3ee70a1026)