JuliusBrussee/caveman · error · ValueError

Unsupported adapter diagnostic

Error message

Unsupported adapter diagnostic

What it means

decline(reason) only accepts the literal reason "unsupported_version"; any other string raises ValueError("Unsupported adapter diagnostic"). This restricts decline() to its intended use: reporting an untested native framework version without sending content or I/O.

Solutions

1. Pass exactly the string "unsupported_version".
2. For other outcomes use the appropriate API (e.g. let optimize() run or handle its errors) rather than decline().
3. Define a constant ADAPTER_UNSUPPORTED_VERSION = "unsupported_version" and reuse it to avoid typos.

Example fix

// before
runtime.decline("too old")  # ValueError
// after
runtime.decline("unsupported_version")

ADAPTER_UNSUPPORTED_VERSION = "unsupported_version"
def decline_safe(rt, reason):
    return rt.decline(reason) if reason == "unsupported_version" else None

def is_adapter_decline_reason(reason) -> bool:
    return reason == "unsupported_version"

try:
    opt = rt.decline(reason)
except ValueError:
    opt = rt.decline("unsupported_version")  # only valid reason

When it happens

Trigger: Calling decline() with any string other than "unsupported_version", e.g. decline("timeout"), decline("not_applicable"), or a typo like "unsupported_version".

Common situations: Adapter authors wiring arbitrary failure reasons into decline(); renaming reason constants after an SDK upgrade; mixing up decline() with the general bypass path.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Caveman delegates through public chat_with_tools methods
• Agno middleware requires a nonempty native session_id
• Agno scope resolver must return a Caveman Scope
• artifact_id is required
• ASGI context must come from authenticated server state

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

Appendix: source

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

            self._closed = True
            if self._async_view is not None:
                self._async_view._shutdown_now()
            if self._receipt_pool is not None:
                self._receipt_pool.shutdown(wait=False, cancel_futures=True)
            self._caps = None
            for connection in tuple(self._connections):
                connection.close()

    def __enter__(self):
        return self

    def __exit__(self, *_):
        self.close()

    def decline(self, reason: str) -> Optimization:
        """Report an untested native framework without sending content or I/O."""
        if reason != "unsupported_version":
            raise ValueError("Unsupported adapter diagnostic")
        if self.mode == "off":
            return Optimization("off", "disabled", (), None, None, "off")
        return self._bypass(reason)

    def _bypass(self, code: str, diagnostic: bool = True) -> Optimization:
        if diagnostic and self._diagnostic:
            try:
                self._diagnostic({"code": code, "cache_continuity": "unavailable"})
            except Exception:
                pass
        if self.strict and diagnostic:
            raise MiddlewareError(code)
        return Optimization("bypassed", code)

    def _http(self, path: str, body: str | None, timeout: float) -> Any:
        if self._closed:
            raise MiddlewareError("closed")
        headers = {"Content-Type": "application/json"}

View on GitHub (pinned to 3ee70a1026)