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

What it means

Raised by _check_langchain_available() in the LangChain memory integration when langchain-core is missing. It guards HeadroomChatMessageHistory, a wrapper around any BaseChatMessageHistory that applies live-zone block compression (SmartCrusher-style per-block compression that never drops messages) once history exceeds the token threshold. When the import fails, BaseChatMessageHistory is stubbed to `object`, so instantiation is impossible anyway; this guard gives an actionable message.

Source

Thrown at headroom/integrations/langchain/memory.py:54

        ToolMessage,
    )

    LANGCHAIN_AVAILABLE = True
except ImportError:
    LANGCHAIN_AVAILABLE = False
    BaseChatMessageHistory = object  # type: ignore[misc,assignment]

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

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"
        )


class HeadroomChatMessageHistory(BaseChatMessageHistory):
    """Wraps any LangChain chat message history with automatic compression.

    When conversation history exceeds the token threshold, automatically
    applies live-zone block compression (per-block content compression on
    the live zone, never dropping messages — that's what the live-zone
    refactor in PR-B1+ replaces the old RollingWindow strategy with).

    This works with ANY memory type because it wraps at the storage layer:
    - ConversationBufferMemory
    - ConversationSummaryMemory
    - ConversationBufferWindowMemory

View on GitHub (pinned to 322425c43b)

Solutions

  1. Install `pip install 'headroom[langchain]'` or `pip install langchain-core`
  2. If langchain-core IS installed, check the module's import block for the specific symbols it imports and verify your langchain-core version still provides them (a version mismatch flips LANGCHAIN_AVAILABLE to False)
  3. Pin known-good versions in requirements.txt

Example fix

# before
history = HeadroomChatMessageHistory(session_id='s1', wrapped=redis_history)

# after
# pip install 'headroom[langchain]'
history = HeadroomChatMessageHistory(session_id='s1', wrapped=redis_history)
Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
assert importlib.util.find_spec('langchain_core'), 'langchain-core required for HeadroomChatMessageHistory'

Type guard

def history_wrapper_ready() -> bool:
    from headroom.integrations.langchain import memory
    return memory.LANGCHAIN_AVAILABLE

Try / catch

try:
    history = HeadroomChatMessageHistory(session_id=sid, wrapped=inner)
except ImportError as e:
    if 'langchain' in str(e):
        history = inner  # fall back to the raw store without compression
    else:
        raise

Prevention

When it happens

Trigger: Constructing HeadroomChatMessageHistory(session_id=..., ...) or calling its methods (add_message, get_messages) when `from langchain_core... import BaseChatMessageHistory` failed at module import time.

Common situations: Adding headroom history compression to a chat app whose environment lacks langchain-core; deploying with a lockfile that excluded optional extras; upgrading LangChain versions where the import path moved so LANGCHAIN_AVAILABLE silently became False even though some langchain package exists.

Related errors

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