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 LangSmith telemetry integration when LANGCHAIN_AVAILABLE is False. Note this module separately tracks LANGSMITH_AVAILABLE; this particular error fires specifically when langchain-core itself is missing, blocking the PendingMetrics/run-annotation machinery that attaches token-savings metrics to LangSmith runs.

Source

Thrown at headroom/integrations/langchain/langsmith.py:73

    BaseCallbackHandler = object  # type: ignore[misc,assignment]
    LLMResult = object  # type: ignore[misc,assignment]

# LangSmith imports - optional
try:
    from langsmith import Client as LangSmithClient

    LANGSMITH_AVAILABLE = True
except ImportError:
    LANGSMITH_AVAILABLE = False
    LangSmithClient = None  # type: ignore[misc,assignment]

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 PendingMetrics:
    """Metrics pending attachment to a LangSmith run."""

    tokens_before: int
    tokens_after: int
    tokens_saved: int
    savings_percent: float
    transforms_applied: list[str]
    timestamp: datetime = field(default_factory=datetime.now)

View on GitHub (pinned to 322425c43b)

Solutions

Install `pip install 'headroom[langchain]'` or `pip install langchain-core`
If you only need LangSmith and have the standalone langsmith SDK, verify langchain-core is also present (`python -c "import langchain_core"`) since this guard requires it
Re-run the observer setup after install

Example fix

# before
observer = HeadroomLangSmithObserver(...)  # raises at first use without langchain-core

# after
# pip install langchain-core langsmith
observer = HeadroomLangSmithObserver(...)

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
assert importlib.util.find_spec('langchain_core'), 'langchain-core required for LangSmith metrics attachment'

Type guard

def langsmith_bridge_ready() -> bool:
    from headroom.integrations.langchain import langsmith
    return langsmith.LANGCHAIN_AVAILABLE and langsmith.LANGSMITH_AVAILABLE

Try / catch

try:
    observer.attach(run)
except ImportError as e:
    logger.warning('Skipping LangSmith metrics: %s', e)

Prevention

Treat telemetry as optional: catch ImportError and continue without metrics
Install langchain-core alongside langsmith, not langsmith alone
Smoke-test the observer in a pre-deploy check

When it happens

Trigger: Initializing or using the Headroom LangSmith observer/bridge (attaching compression metrics like tokens_before/tokens_after to LangSmith runs) in an environment without langchain-core installed.

Common situations: Installing the `langsmith` package alone and assuming that suffices — this integration also requires langchain-core; monitoring setups added after the fact to an app that never depended on LangChain; partial extras installs.

Related errors

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