{"record":{"id":"1168a5127bdcf3f5","repo":"headroomlabs-ai/headroom","slug":"langchain-is-required-for-this-integration-instal","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/agents.py","lineNumber":51,"sourceCode":"try:\n    from langchain_core.tools import BaseTool, StructuredTool, Tool\n\n    LANGCHAIN_AVAILABLE = True\nexcept ImportError:\n    LANGCHAIN_AVAILABLE = False\n    BaseTool = object  # type: ignore[misc,assignment]\n    StructuredTool = object  # type: ignore[misc,assignment]\n    Tool = object  # type: ignore[misc,assignment]\n\nfrom headroom.integrations.mcp import compress_tool_result\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\n@dataclass\nclass ToolCompressionMetrics:\n    \"\"\"Metrics from a single tool compression.\"\"\"\n\n    tool_name: str\n    timestamp: datetime\n    chars_before: int\n    chars_after: int\n    chars_saved: int\n    compression_ratio: float\n    was_compressed: bool\n","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/langchain/agents.py#L33-L69","documentation":"Raised by _check_langchain_available() in the LangChain integration when langchain-core could not be imported at module load (LANGCHAIN_AVAILABLE=False; BaseTool/StructuredTool/Tool stubbed to object). The message offers two install routes because the integration only needs langchain-core, not the full langchain metapackage — 'pip install headroom[langchain]' or plain 'pip install langchain-core'.","triggerScenarios":"Using headroom's LangChain tool/agent wrappers without langchain-core installed; or langchain installed but langchain-core missing/mismatched after a partial upgrade (langchain 0.1+ split makes this common); wrong venv.","commonSituations":"Mixing langchain and langchain-core versions after upgrades; slim deployments that installed headroom alone; CI caches with stale langchain-core; teams assuming the full 'langchain' package is required when core suffices.","solutions":["pip install langchain-core (smallest fix — the integration imports only core primitives).","Or pip install 'headroom[langchain]' to get the curated extra.","If langchain is installed but broken: pip install -U langchain-core langchain to realign the split packages.","Gate integration use behind the availability check / LANGCHAIN_AVAILABLE flag."],"exampleFix":"# before\nfrom headroom.integrations.langchain.agents import create_headroom_tool  # ImportError\n\n# after\n$ python -m pip install langchain-core\nfrom headroom.integrations.langchain.agents import create_headroom_tool  # ok","handlingStrategy":"type-guard","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"langchain_core\") is None:\n    raise SystemExit(\"LangChain integration needs langchain-core: pip install langchain-core\")","typeGuard":"import importlib.util\n\ndef langchain_integration_ready() -> bool:\n    \"\"\"True when langchain-core (all this integration requires) is importable.\"\"\"\n    return importlib.util.find_spec(\"langchain_core\") is not None","tryCatchPattern":"try:\n    from headroom.integrations.langchain.agents import create_headroom_tool\nexcept ImportError as e:\n    if \"LangChain is required\" in str(e):\n        sys.exit(\"pip install headroom[langchain]  # or: pip install langchain-core\")\n    raise","preventionTips":["langchain-core alone is sufficient — don't require the full langchain metapackage.","After langchain upgrades, verify 'import langchain_core' still works; version splits commonly break it.","Declare the headroom[langchain] extra in project requirements instead of relying on ambient installs."],"tags":["langchain","import-error","optional-dependency","integration","extras"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}