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 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'.

Source

Thrown at headroom/integrations/langchain/agents.py:51

try:
    from langchain_core.tools import BaseTool, StructuredTool, Tool

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

from headroom.integrations.mcp import compress_tool_result

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


@dataclass
class ToolCompressionMetrics:
    """Metrics from a single tool compression."""

    tool_name: str
    timestamp: datetime
    chars_before: int
    chars_after: int
    chars_saved: int
    compression_ratio: float
    was_compressed: bool

View on GitHub (pinned to 322425c43b)

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.

Example fix

# before
from headroom.integrations.langchain.agents import create_headroom_tool  # ImportError

# after
$ python -m pip install langchain-core
from headroom.integrations.langchain.agents import create_headroom_tool  # ok

Defensive patterns

Strategy: type-guard

Validate before calling

import importlib.util

if importlib.util.find_spec("langchain_core") is None:
    raise SystemExit("LangChain integration needs langchain-core: pip install langchain-core")

Type guard

import importlib.util

def langchain_integration_ready() -> bool:
    """True when langchain-core (all this integration requires) is importable."""
    return importlib.util.find_spec("langchain_core") is not None

Try / catch

try:
    from headroom.integrations.langchain.agents import create_headroom_tool
except ImportError as e:
    if "LangChain is required" in str(e):
        sys.exit("pip install headroom[langchain]  # or: pip install langchain-core")
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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