langchain-ai/langgraph · error · ValueError

Package name ' ' used in local dep ' ' is reserved. Rename…

Error message

Package name '{name}' used in local dep '{ref}' is reserved. Rename the directory.

What it means

Dependency-graph validation while the CLI collects local dependencies from langgraph.json: a local path dependency's directory name collides with a reserved package name (langgraph, langgraph-api/_api, langchain-core/_core, src, pydantic, orjson, fastapi, uvicorn, psycopg, httpx, langsmith, and any previously claimed name). Reserved names are needed by the langgraph-api runtime itself, so a local dir using one would shadow it inside the built image.

Solutions

  1. Rename the local dependency directory to something unique, e.g. my-agent-utils instead of src or langgraph-utils
  2. Remove the local dep if it was meant to alias a real package
  3. Avoid naming any project directory after langchain/langgraph internals or common deps already installed in the image
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at libs/cli/langgraph_cli/config.py:731 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/5d0c47e3ddee6402. Report an issue: GitHub.

Appendix: source

Thrown at libs/cli/langgraph_cli/config.py:731

        "src",
        "langgraph-api",
        "langgraph_api",
        "langgraph",
        "langchain-core",
        "langchain_core",
        "pydantic",
        "orjson",
        "fastapi",
        "uvicorn",
        "psycopg",
        "httpx",
        "langsmith",
    }
    counter = Counter()

    def check_reserved(name: str, ref: str):
        if name in reserved:
            raise ValueError(
                f"Package name '{name}' used in local dep '{ref}' is reserved. "
                "Rename the directory."
            )
        reserved.add(name)

    pip_reqs = []
    real_pkgs = {}
    faux_pkgs = {}
    working_dir: str | None = None
    additional_contexts: list[pathlib.Path] = []

    for local_dep in config["dependencies"]:
        if not local_dep.startswith("."):
            # If the dependency is not a local path, skip it
            continue

        # Verify that the local dependency can be resolved
        # (e.g., this would raise an informative error if a user mistyped a path).

View on GitHub (pinned to 38031739e5)