JuliusBrussee/caveman · error · ImportError

Install caveman-middleware[litellm] to use the LiteLLM…

Error message

Install caveman-middleware[litellm] to use the LiteLLM adapter

What it means

Importing the LiteLLM adapter requires the optional 'litellm' package (plus litellm.integrations.custom_logger). When the import fails with ModuleNotFoundError, the adapter re-raises it as ImportError with this message, chaining the original error. The adapter is shipped as an extra so the core package stays dependency-light.

Solutions

Run pip install "caveman-middleware[litellm]" in the active environment
Verify with `which python` / `pip show litellm` that you are in the same environment that runs your app
If litellm is installed but fails to import, fix or reinstall litellm itself (pip install --force-reinstall litellm)
Pin a litellm version compatible with your Python if the install itself fails

Example fix

// before
from caveman_middleware.litellm import CavemanLiteLLM
# ImportError: Install caveman-middleware[litellm] ...

// after
# shell: pip install "caveman-middleware[litellm]"
from caveman_middleware.litellm import CavemanLiteLLM

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
if importlib.util.find_spec("litellm") is None:
    raise SystemExit('Install with: pip install "caveman-middleware[litellm]"')

Type guard

def litellm_available() -> bool:
    return importlib.util.find_spec("litellm") is not None

Try / catch

try:
    from caveman_middleware.litellm import CavemanLiteLLM
except ImportError as e:
    logger.error("LiteLLM adapter unavailable: %s", e)
    CavemanLiteLLM = None  # or fall back to another adapter

Prevention

Install framework adapters with extras: caveman-middleware[litellm]
Declare the extra in your project's dependencies/requirements
Import adapters at startup (fail fast) rather than lazily at request time
Run the app with the same interpreter/venv you pip-install into

When it happens

Trigger: Any import of caveman_middleware.litellm (or use of the adapter entry point) while the 'litellm' distribution is not installed in the current Python environment.

Common situations: Installed caveman-middleware without the [litellm] extra; using a different virtualenv/interpreter than the one that has litellm; deploying to a container where extras were pruned; litellm broken/unimportable so its import also raises ModuleNotFoundError.

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/060a4a318b06e9c5. Report an issue: GitHub.

Appendix: source

Thrown at packages/middleware/python/caveman_middleware/litellm.py:21

Install the callback after original-content policy hooks. A proxy scope resolver
receives the authenticated UserAPIKeyAuth object, never a model-supplied identity.
LiteLLM remains the sole inference hop and owns retries, fallbacks and streams.
"""
from __future__ import annotations

import contextlib
import contextvars
import threading
import time
import uuid
from collections import OrderedDict
from dataclasses import dataclass

try:
    import litellm as native
    from litellm.integrations.custom_logger import CustomLogger
except ModuleNotFoundError as error:
    raise ImportError("Install caveman-middleware[litellm] to use the LiteLLM adapter") from error

from caveman_cloud.middleware import MiddlewareError, MiddlewareRuntime, Scope
from ._native import Attempt, NativeSession, owner, plain
from ._versions import matches_framework
from ._usage import usage

_active = contextvars.ContextVar("caveman_litellm_request", default=None)
_sync_router = contextvars.ContextVar("caveman_litellm_sync_router", default=None)
_prepared_sync = contextvars.ContextVar("caveman_litellm_prepared_sync", default=None)
_registration_lock = threading.RLock()
_KEY = "caveman_middleware_registration"


@dataclass
class _Request:
    scope: Scope
    logical_id: str
    expires: float

View on GitHub (pinned to 3ee70a1026)