{"record":{"id":"5b30a47db3cbb072","repo":"headroomlabs-ai/headroom","slug":"langchain-is-required-for-this-integration-instal-5b30a4","errorCode":null,"errorMessage":"LangChain is required for this integration. Install with: pip install headroom[langchain] or: pip install langchain-core langchain-openai","messagePattern":"LangChain is required for this integration\\. Install with: pip install headroom\\[langchain\\] or: pip install langchain-core langchain-openai","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/langchain/chat_model.py","lineNumber":76,"sourceCode":"    BaseChatModel = object  # type: ignore[misc,assignment]\n    BaseCallbackHandler = object  # type: ignore[misc,assignment]\n    ConfigDict = lambda **kwargs: {}  # type: ignore[assignment,misc]  # noqa: E731\n    Field = lambda **kwargs: None  # type: ignore[assignment]  # noqa: E731\n    PrivateAttr = lambda **kwargs: None  # type: ignore[assignment]  # noqa: E731\n\nfrom headroom import HeadroomConfig, HeadroomMode\nfrom headroom.providers import OpenAIProvider\nfrom headroom.transforms import TransformPipeline\n\nfrom .providers import get_headroom_provider, get_model_name_from_langchain\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 langchain-openai\"\n        )\n\n\ndef _tool_call_args_to_json(tc: dict[str, Any] | Any) -> str:\n    \"\"\"Normalize tool call arguments to JSON string for OpenAI format.\n\n    LangChain can provide 'args' (dict) or 'arguments' (str) depending on source.\n    \"\"\"\n    if \"args\" in tc:\n        val = tc[\"args\"]\n        return json.dumps(val) if isinstance(val, dict) else str(val)\n    if \"arguments\" in tc:\n        val = tc[\"arguments\"]\n        return val if isinstance(val, str) else json.dumps(val)\n    if \"function\" in tc and isinstance(tc[\"function\"], dict):","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/langchain/chat_model.py#L58-L94","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the extra: `pip install 'headroom[langchain]'` (pulls langchain-core and langchain-openai)","Or install directly: `pip install langchain-core langchain-openai`","Verify with `python -c \"import langchain_core, langchain_openai; import headroom.integrations.langchain.chat_model\"` before running your app","If intentional, check availability first via the module's availability flag instead of letting the ImportError propagate"],"exampleFix":"# before\nfrom headroom.integrations.langchain.chat_model import HeadroomChatModel\nmodel = HeadroomChatModel(model='gpt-4o')  # ImportError if langchain missing\n\n# after\n# pip install 'headroom[langchain]'\nfrom headroom.integrations.langchain.chat_model import HeadroomChatModel\nmodel = HeadroomChatModel(model='gpt-4o')","handlingStrategy":"validation","validationCode":"import importlib.util\nlangchain_ok = importlib.util.find_spec('langchain_core') is not None and importlib.util.find_spec('langchain_openai') is not None\nif not langchain_ok:\n    raise SystemExit('Install headroom[langchain] before using the chat model')","typeGuard":"def has_langchain_chat_model() -> bool:\n    from headroom.integrations.langchain import chat_model\n    return chat_model.LANGCHAIN_AVAILABLE","tryCatchPattern":"try:\n    model = HeadroomChatModel(...)\nexcept ImportError as e:\n    if 'headroom[langchain]' in str(e):\n        logger.error('Missing optional dep: %s', e)\n        raise\n    raise","preventionTips":["Declare headroom[langchain] (not bare headroom) in pyproject/requirements when using LangChain integrations","Run a startup dependency assertion that fails fast before serving traffic","Add an import smoke test for headroom.integrations.langchain to CI"],"tags":["langchain","import-error","optional-dependency","installation"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}