headroomlabs-ai/headroom · error · ImportError

LangChain is required for this integration. Install with: pi

Error message

LangChain is required for this integration. Install with: pip install headroom[langchain] or: pip install langchain-core langchain-openai

What it means

Raised by _check_langchain_available() in headroom/integrations/langchain/chat_model.py when the module-level LANGCHAIN_AVAILABLE flag is False, i.e. the initial `import langchain_core`/`langchain_openai` attempt failed at import time. It guards HeadroomChatModel, the LangChain-compatible chat model wrapper, so any attempt to instantiate or use it without the optional LangChain dependency fails fast with install instructions.

Source

Thrown at headroom/integrations/langchain/chat_model.py:76

    BaseChatModel = object  # type: ignore[misc,assignment]
    BaseCallbackHandler = object  # type: ignore[misc,assignment]
    ConfigDict = lambda **kwargs: {}  # type: ignore[assignment,misc]  # noqa: E731
    Field = lambda **kwargs: None  # type: ignore[assignment]  # noqa: E731
    PrivateAttr = lambda **kwargs: None  # type: ignore[assignment]  # noqa: E731

from headroom import HeadroomConfig, HeadroomMode
from headroom.providers import OpenAIProvider
from headroom.transforms import TransformPipeline

from .providers import get_headroom_provider, get_model_name_from_langchain

logger = logging.getLogger(__name__)


def _check_langchain_available() -> None:
    """Raise ImportError if LangChain is not installed."""
    if not LANGCHAIN_AVAILABLE:
        raise ImportError(
            "LangChain is required for this integration. "
            "Install with: pip install headroom[langchain] "
            "or: pip install langchain-core langchain-openai"
        )


def _tool_call_args_to_json(tc: dict[str, Any] | Any) -> str:
    """Normalize tool call arguments to JSON string for OpenAI format.

    LangChain can provide 'args' (dict) or 'arguments' (str) depending on source.
    """
    if "args" in tc:
        val = tc["args"]
        return json.dumps(val) if isinstance(val, dict) else str(val)
    if "arguments" in tc:
        val = tc["arguments"]
        return val if isinstance(val, str) else json.dumps(val)
    if "function" in tc and isinstance(tc["function"], dict):

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the extra: `pip install 'headroom[langchain]'` (pulls langchain-core and langchain-openai)
2. Or install directly: `pip install langchain-core langchain-openai`
3. Verify with `python -c "import langchain_core, langchain_openai; import headroom.integrations.langchain.chat_model"` before running your app
4. If intentional, check availability first via the module's availability flag instead of letting the ImportError propagate

Example fix

# before
from headroom.integrations.langchain.chat_model import HeadroomChatModel
model = HeadroomChatModel(model='gpt-4o')  # ImportError if langchain missing

# after
# pip install 'headroom[langchain]'
from headroom.integrations.langchain.chat_model import HeadroomChatModel
model = HeadroomChatModel(model='gpt-4o')

import importlib.util
langchain_ok = importlib.util.find_spec('langchain_core') is not None and importlib.util.find_spec('langchain_openai') is not None
if not langchain_ok:
    raise SystemExit('Install headroom[langchain] before using the chat model')

def has_langchain_chat_model() -> bool:
    from headroom.integrations.langchain import chat_model
    return chat_model.LANGCHAIN_AVAILABLE

try:
    model = HeadroomChatModel(...)
except ImportError as e:
    if 'headroom[langchain]' in str(e):
        logger.error('Missing optional dep: %s', e)
        raise
    raise

When it happens

Trigger: Calling any constructor or method on the Headroom LangChain chat model (e.g. HeadroomChatModel(...).invoke(...)) in an environment where `import langchain_core` or `langchain_openai` raised ImportError when the module was first loaded; the stub classes were substituted with `object` and this check converts that into an explicit error.

Common situations: Installing plain `pip install headroom` without the [langchain] extra; a venv where langchain-core was uninstalled or never present; partial installs where langchain-core exists but langchain-openai is missing (chat_model needs both per the message); CI environments that prune optional dependencies.

Related errors

• LangChain is required for this integration. Install with: pi
• LangChain is required for this integration. Install with: pi
• anthropic package required. Install with: pip install anthro
• openai package required. Install with: pip install openai
• ollama package required. Install with: pip install ollama

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/5b30a47db3cbb072. Report an issue: GitHub.