langchain-ai/langgraph · error · ValueError

Node.js version must be major version only

Error message

Node.js version must be major version only

What it means

Format validation in the CLI's _parse_node_version helper: the node_version config value must be a bare major version (e.g. '20'), because only major Node.js versions are supported in generated Dockerfiles. The parser calls int() on the whole string; values like '20.11', 'v20', or '20.x' fail conversion and hit this UsageError.

Solutions

1. Set node_version to a major version integer string, e.g. "node_version": "20"
2. Remove prefixes ('v') and minor/patch suffixes from the value in langgraph.json

When it happens

Trigger: Thrown at libs/cli/langgraph_cli/config.py:149 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/aea6aac08387e876. Report an issue: GitHub.

Appendix: source

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

                "RUN rm /usr/bin/uv /usr/bin/uvx\n# -- End of build deps removal --"
            )
    return "\n".join(commands)


def _parse_version(version_str: str) -> tuple[int, int]:
    """Parse a version string into a tuple of (major, minor)."""
    try:
        major, minor = map(int, version_str.split("-")[0].split("."))
        return (major, minor)
    except ValueError:
        raise click.UsageError(f"Invalid version format: {version_str}") from None


def _parse_node_version(version_str: str) -> int:
    """Parse a Node.js version string into a major version number."""
    try:
        if "." in version_str:
            raise ValueError("Node.js version must be major version only")
        return int(version_str)
    except ValueError:
        raise click.UsageError(
            f"Invalid Node.js version format: {version_str}. "
            "Use major version only (e.g., '20')."
        ) from None


def _parse_api_version_parts(version_str: str) -> tuple[int, ...]:
    """Parse an API version into numeric components.

    Supports optional prerelease suffixes, e.g. `0.9.0rc1`.
    """
    version_core = version_str.split("-", 1)[0]
    match = _API_VERSION_PATTERN.fullmatch(version_core)
    if not match:
        raise ValueError("Version must be major or major.minor or major.minor.patch.")
    return tuple(int(part) for part in match.groups() if part is not None)

View on GitHub (pinned to 38031739e5)