langchain-ai/langchain · error · ValueError

Expected {package} version to be >= {gte_version}. Received

Error message

Expected {package} version to be >= {gte_version}. Received {imported_version}.

What it means

Raised by the version-check utility in `langchain_core.utils.utils` when an installed optional package's version is older than the minimum version (`gte_version`) that a LangChain integration requires. The check parses the imported package's `__version__` and compares it against the declared floor, raising `ValueError` when the installed release predates it. This exists to fail fast with a clear message instead of hitting obscure `AttributeError`/`ImportError` crashes from older APIs.

Source

Thrown at libs/core/langchain_core/utils/utils.py:190

        raise ValueError(msg)
    if lte_version is not None and imported_version > parse(lte_version):
        msg = (
            f"Expected {package} version to be <= {lte_version}. Received "
            f"{imported_version}."
        )
        raise ValueError(msg)
    if gt_version is not None and imported_version <= parse(gt_version):
        msg = (
            f"Expected {package} version to be > {gt_version}. Received "
            f"{imported_version}."
        )
        raise ValueError(msg)
    if gte_version is not None and imported_version < parse(gte_version):
        msg = (
            f"Expected {package} version to be >= {gte_version}. Received "
            f"{imported_version}."
        )
        raise ValueError(msg)


def get_pydantic_field_names(pydantic_cls: Any) -> set[str]:
    """Get field names, including aliases, for a pydantic class.

    Args:
        pydantic_cls: Pydantic class.

    Returns:
        Field names.
    """
    all_required_field_names = set()
    if is_pydantic_v1_subclass(pydantic_cls):
        for field in pydantic_cls.__fields__.values():
            all_required_field_names.add(field.name)
            if field.has_alias:
                all_required_field_names.add(field.alias)
    else:  # Assuming pydantic 2 for now

View on GitHub (pinned to e32fa9a52e)

Solutions

Upgrade the offending package to at least the version named in the message, e.g. `uv pip install -U openai` (or whatever `{package}` is).
If using a lockfile, refresh it: run `uv sync --all-groups` / `uv lock --upgrade-package <package>` from the package directory.
Check for duplicate installations (`uv pip list | grep <package>` or `pip show <package>`) and remove the stale copy that shadows the upgraded one.
If you cannot upgrade, pin the LangChain integration to an older release whose minimum version requirement you already satisfy.

Example fix

# before
uv pip install "openai==0.27.0"
from langchain_openai import ChatOpenAI  # ValueError: Expected openai version to be >= 1.x

# after
uv pip install -U openai
from langchain_openai import ChatOpenAI  # ok

Defensive patterns

Strategy: validation

Validate before calling

from importlib.metadata import version, PackageNotFoundError
from packaging.version import parse

MIN_VERSIONS = {"openai": "1.60.0"}  # floors required by your integrations

for pkg, floor in MIN_VERSIONS.items():
    try:
        installed = parse(version(pkg))
    except PackageNotFoundError:
        raise SystemExit(f"{pkg} is not installed")
    if installed < parse(floor):
        raise SystemExit(f"Upgrade {pkg}: have {installed}, need >= {floor}")

Try / catch

try:
    from langchain_openai import ChatOpenAI
except ValueError as e:  # version guard raised at import time
    raise SystemExit(f"Dependency version problem: {e}. Run `uv sync --all-groups`.") from e

Prevention

Keep one lockfile per package (`uv.lock`) and install only through `uv sync`, never ad-hoc pip installs.
Run `uv lock --upgrade` in a scheduled CI job so dependency floors surface as PR failures, not runtime errors.
Print dependency versions at startup during debugging to catch shadowed/stale installs.

When it happens

Trigger: Importing or instantiating an integration whose module-level code calls the version guard (e.g. `langchain_openai` requiring `openai >= X`) while the installed dependency is older than `gte_version`. Also triggered by explicitly calling the check helper with a `gte_version` argument against an outdated environment.

Common situations: Pinned or frozen `requirements.txt`/`uv.lock` with stale optional dependencies after upgrading `langchain-core` or a partner package; CI images built from old base layers; mixing system-installed and venv-installed packages so an old version shadows the new one.

Related errors

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/b81c0e5f0407b176. Report an issue: GitHub.