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 LangGraph integration module when LANGCHAIN_AVAILABLE is False, meaning langchain-core could not be imported at module load. It guards the LangGraph middleware/wrapper that injects the CCR tool (CCR_TOOL_NAME) and SmartCrusher compression into LangGraph agents, plus the BeaconCompressionObserver telemetry hook.

Source

Thrown at headroom/integrations/langchain/langgraph.py:61

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

from headroom.ccr.tool_injection import CCR_TOOL_NAME
from headroom.config import is_tool_excluded
from headroom.telemetry.session import BeaconCompressionObserver
from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig

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


def _estimate_tokens(text: str) -> int:
    """Estimate token count using ~4 characters per token heuristic."""
    if not text:
        return 0
    return len(text) // 4


@dataclass
class ToolMessageCompressionMetrics:
    """Metrics from compressing a single ToolMessage."""

    request_id: str

View on GitHub (pinned to 322425c43b)

Solutions

Install the extra: `pip install 'headroom[langchain]'`
Or `pip install langchain-core` (langgraph users usually already need it, so check for a broken/partial install)
Confirm with `python -c "import langchain_core"` and retry the integration import

Example fix

# before
from headroom.integrations.langchain.langgraph import apply_headroom_to_graph  # ImportError at call time

# after
# pip install 'headroom[langchain]'
from headroom.integrations.langchain.langgraph import apply_headroom_to_graph

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

def langgraph_ready() -> bool:
    from headroom.integrations.langchain import langgraph
    return langgraph.LANGCHAIN_AVAILABLE

Try / catch

try:
    from headroom.integrations.langchain.langgraph import build_headroom_graph
except ImportError as e:
    logger.warning('LangGraph integration unavailable: %s', e)
    graph = build_plain_graph()  # degrade to unwrapped graph

Prevention

Pin headroom[langchain] in the deploy image
Gate integration code behind an availability check so non-LangGraph users never hit the guard
Restart processes after installing langchain-core — the flag is computed once at import

When it happens

Trigger: Importing or invoking the Headroom LangGraph wrapper functions (tool injection, smart-crusher transforms) when langchain-core is not installed; any code path that calls into this module's public API triggers the guard at call time.

Common situations: Using headroom's core features (which do not need LangChain) but then wiring it into a LangGraph agent in an environment that only has `pip install headroom`; mixing dependency groups so langgraph is installed but langchain-core is not; fresh CI containers without the [langchain] extra.

Related errors

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