JuliusBrussee/caveman · error · ImportError

Install caveman-middleware[anthropic] to use the Anthropic…

Error message

Install caveman-middleware[anthropic] to use the Anthropic adapter

What it means

The Anthropic adapter is an optional extra: it imports the `anthropic` package (Anthropic, AsyncAnthropic, Middleware, etc.) at module import time. If the package is missing, the module raises ImportError telling you to install the caveman-middleware[anthropic] extra.

Solutions

  1. Install the extra: pip install 'caveman-middleware[anthropic]'
  2. Add the extra to your requirements/pyproject dependencies
  3. If anthropic is present but fails to import for another reason, inspect the chained exception (__cause__) for the real ModuleNotFoundError

Example fix

// before
pip install caveman-middleware
// after
pip install "caveman-middleware[anthropic]"
Defensive patterns

Strategy: fallback

Validate before calling

try:
    import anthropic  # noqa: F401
    ANTHROPIC_AVAILABLE = True
except ModuleNotFoundError:
    ANTHROPIC_AVAILABLE = False

Try / catch

try:
    from caveman_middleware import anthropic as caveman_anthropic
except ImportError as e:
    if 'caveman-middleware[anthropic]' in str(e):
        caveman_anthropic = None  # degrade to non-Anthropic path
    else:
        raise

Prevention

When it happens

Trigger: Importing caveman_middleware.anthropic (or a module that imports it) without the anthropic dependency installed.

Common situations: Fresh environment installed with plain `pip install caveman-middleware` (no extras); CI image missing optional dependencies; switching code paths to Anthropic without updating requirements.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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

Appendix: source

Thrown at packages/middleware/python/caveman_middleware/anthropic.py:15

"""Anthropic 1.4 public per-attempt middleware and native tool runners."""
from __future__ import annotations

import functools
import asyncio
import json
import uuid
from dataclasses import dataclass
from urllib.parse import urlsplit

try:
    from anthropic import Anthropic, AsyncAnthropic, Middleware, APIRequest, __version__
    from anthropic.lib.tools import BetaBuiltinFunctionTool, BetaAsyncBuiltinFunctionTool
except ModuleNotFoundError as error:
    raise ImportError("Install caveman-middleware[anthropic] to use the Anthropic adapter") from error

from caveman_cloud.middleware import MiddlewareRuntime, AsyncMiddlewareRuntime
from ._httpx2 import observe_response
from ._native import NativeSession, owner, plain
from ._versions import in_range


class CavemanAnthropicMiddleware(Middleware):
    """Append after the application's authorization and original-content guards."""
    def __init__(self, runtime, scope, *, _binding=None, _overhead=None, _logical_call_id=None, _is_registered=None):
        self.session = NativeSession(runtime, scope, adapter_id="anthropic-sdk", framework_version="1.4.0", protocol="anthropic-messages",
                                     binding=_binding, overhead=_overhead, logical_call_id=_logical_call_id, is_registered=_is_registered,
                                     passive_reason=None if in_range(__version__, "1.4", "2") else "unsupported_version")

    @staticmethod
    def eligible(request: APIRequest):
        if request.method.upper() != "POST" or urlsplit(request.url).path not in ("/v1/messages", "/messages"):
            return False

View on GitHub (pinned to 3ee70a1026)