{"record":{"id":"4497ef91116dd21b","repo":"headroomlabs-ai/headroom","slug":"langchain-is-required-for-this-integration-instal-4497ef","errorCode":null,"errorMessage":"LangChain is required for this integration. Install with: pip install headroom[langchain] or: pip install langchain-core","messagePattern":"LangChain is required for this integration\\. Install with: pip install headroom\\[langchain\\] or: pip install langchain-core","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/langchain/langgraph.py","lineNumber":61,"sourceCode":"\n    LANGCHAIN_AVAILABLE = True\nexcept ImportError:\n    LANGCHAIN_AVAILABLE = False\n    BaseMessage = object  # type: ignore[misc,assignment]\n    ToolMessage = object  # type: ignore[misc,assignment]\n\nfrom headroom.ccr.tool_injection import CCR_TOOL_NAME\nfrom headroom.config import is_tool_excluded\nfrom headroom.telemetry.session import BeaconCompressionObserver\nfrom headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_langchain_available() -> None:\n    \"\"\"Raise ImportError if LangChain is not installed.\"\"\"\n    if not LANGCHAIN_AVAILABLE:\n        raise ImportError(\n            \"LangChain is required for this integration. \"\n            \"Install with: pip install headroom[langchain] \"\n            \"or: pip install langchain-core\"\n        )\n\n\ndef _estimate_tokens(text: str) -> int:\n    \"\"\"Estimate token count using ~4 characters per token heuristic.\"\"\"\n    if not text:\n        return 0\n    return len(text) // 4\n\n\n@dataclass\nclass ToolMessageCompressionMetrics:\n    \"\"\"Metrics from compressing a single ToolMessage.\"\"\"\n\n    request_id: str","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/langchain/langgraph.py#L43-L79","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nfrom headroom.integrations.langchain.langgraph import apply_headroom_to_graph  # ImportError at call time\n\n# after\n# pip install 'headroom[langchain]'\nfrom headroom.integrations.langchain.langgraph import apply_headroom_to_graph","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec('langchain_core'), 'langchain-core required for the LangGraph integration'","typeGuard":"def langgraph_ready() -> bool:\n    from headroom.integrations.langchain import langgraph\n    return langgraph.LANGCHAIN_AVAILABLE","tryCatchPattern":"try:\n    from headroom.integrations.langchain.langgraph import build_headroom_graph\nexcept ImportError as e:\n    logger.warning('LangGraph integration unavailable: %s', e)\n    graph = build_plain_graph()  # degrade to unwrapped graph","preventionTips":["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"],"tags":["langgraph","langchain","import-error","optional-dependency"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}