JuliusBrussee/caveman · error · ImportError

Install caveman-middleware[google] to use the Google adapter

Error message

Install caveman-middleware[google] to use the Google adapter

What it means

The Google adapter imports optional Google Gen AI dependencies (httpx, google.genai, google.genai.chats) at module import time. If the google-genai package is missing, this ImportError is raised as a cause-chained error telling you to install the optional extra, instead of surfacing a raw ModuleNotFoundError.

Solutions

1. Run pip install "caveman-middleware[google]".
2. Add caveman-middleware[google] to your dependency manifest and reinstall.
3. Verify with python -c "from google import genai"; if it fails, install/repair google-genai at a supported version.

Example fix

// before
pip install caveman-middleware
// after
pip install "caveman-middleware[google]"

try:
    from google import genai
except ModuleNotFoundError:
    raise RuntimeError("Run: pip install 'caveman-middleware[google]'")

def google_extra_installed() -> bool:
    import importlib.util
    return importlib.util.find_spec("google.genai") is not None

try:
    from caveman_middleware import google as caveman_google
except ImportError as e:
    logging.error("Install the extra: pip install 'caveman-middleware[google]' (%s)", e)
    raise

When it happens

Trigger: Importing caveman_middleware.google (or code that imports it) in an environment where google-genai (or httpx) is not installed. Occurs at import time, before any adapter call.

Common situations: Installing caveman-middleware without the [google] extra; a slim deployment image lacking the extra; a google-genai upgrade removing submodules like google.genai.chats, which also surfaces as 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

• Expected a Google Client and synchronous MiddlewareRuntime
• Expected a native Google Chat or AsyncChat
• Install caveman-middleware[agno] to use the Agno adapter
• Install caveman-middleware[crewai] to use the CrewAI adapter
• Match the sync/async runtime to the chat

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

Appendix: source

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

Install the transport through HttpOptions.httpx_client/httpx_async_client. Wrap
the existing client or chat to register the recovery executor in its native AFC
loop. The SDK keeps provider auth, Vertex configuration, retries and history.
"""
import codecs
import contextvars
import functools
import json
import re
import uuid
from urllib.parse import urlsplit

try:
    import httpx
    from google import genai
    from google.genai import types
    from google.genai.chats import Chat, AsyncChat
except ModuleNotFoundError as error:
    raise ImportError("Install caveman-middleware[google] to use the Google adapter") from error

from caveman_cloud.middleware import Adapter, Candidate, MiddlewareRuntime, AsyncMiddlewareRuntime, sha256
from ._native import Attempt, manifest, owner, plain
from ._versions import supports_framework
from ._usage import usage
from ._google_wire import parse, patch

_invocation = contextvars.ContextVar("caveman_google_invocation", default=None)


def _get(value, name, default=None):
    if plain(value):
        pieces = name.split("_")
        alias = pieces[0] + "".join(piece.title() for piece in pieces[1:])
        return value.get(name, value.get(alias, default))
    return getattr(value, name, default)

View on GitHub (pinned to 3ee70a1026)