Implementation:Langchain ai Langgraph Validate Config File

Property	Value
API	`validate_config_file` and `validate_config`
Type	API Doc + Pattern Doc (Config schema)
Source	`libs/cli/langgraph_cli/config.py`
Library	langgraph-cli
Related Workflow	CLI_Deployment

Overview

The `validate_config_file` and `validate_config` functions provide the entry point for loading and validating a LangGraph project configuration. `validate_config_file` reads a JSON configuration file from disk and delegates to `validate_config`, which enforces the `Config` TypedDict schema, checks version constraints, validates dependency declarations, and ensures all required fields are present and well-formed. The `Config` TypedDict at `libs/cli/langgraph_cli/schemas.py` defines the canonical shape of the configuration.

Description

Config TypedDict Schema

The `Config` TypedDict (defined at `libs/cli/langgraph_cli/schemas.py:L530`) specifies all recognized top-level configuration keys:

Field	Type	Description
`python_version`	`str`	Python version in `major.minor` format (minimum `3.11`)
`node_version`	None`	Node.js major version (minimum `20`)
`api_version`	None`	LangGraph API server semantic version
`base_image`	None`	Override default Docker base image
`image_distro`	None`	Linux distribution for base image
`pip_config_file`	None`	Path to a pip config file
`pip_installer`	None`	Package installer: `"auto"`, `"pip"`, or `"uv"`
`dockerfile_lines`	`list[str]`	Additional Dockerfile instructions
`dependencies`	`list[str]`	Python dependencies (PyPI or local paths)
`graphs`	`dict[str, str]`	Mapping of graph IDs to import paths
`env`	str`	Environment variables or path to `.env` file
`store`	None`	Long-term memory store configuration
`checkpointer`	None`	Checkpointing configuration
`auth`	None`	Authentication configuration
`encryption`	None`	Encryption configuration
`http`	None`	HTTP server configuration
`webhooks`	None`	Webhooks configuration
`ui`	None`	UI component definitions
`keep_pkg_tools`	list[str] | None`	Retain packaging tools in final image

validate_config_file

Loads a JSON configuration file, parses it, validates it via `validate_config`, and additionally checks for `package.json` Node.js engine compatibility if Node.js graphs are present.

validate_config

Performs comprehensive validation of a configuration dictionary:

• Detects whether graphs are Python or Node.js based on file extensions.
• Assigns default `python_version` (3.11) and `node_version` (20) as appropriate.
• Validates version format and minimum version constraints.
• Ensures at least one dependency is listed for Python projects.
• Ensures at least one graph is registered.
• Validates `image_distro` against allowed values.
• Validates `pip_installer` against allowed values.
• Validates `auth.path`, `encryption.path`, and `http.app` format (`"file.py:attribute"`).
• Validates `keep_pkg_tools` entries.

Code Reference

Source Location

Function	File	Line
`validate_config_file`	`libs/cli/langgraph_cli/config.py`	L273
`validate_config`	`libs/cli/langgraph_cli/config.py`	L111
`Config` TypedDict	`libs/cli/langgraph_cli/schemas.py`	L530

Signature

def validate_config_file(config_path: pathlib.Path) -> Config:
    """Load and validate a configuration file."""
    ...

def validate_config(config: Config) -> Config:
    """Validate a configuration dictionary."""
    ...

Import

from langgraph_cli.config import validate_config_file, validate_config
from langgraph_cli.schemas import Config

I/O Contract

validate_config_file

Direction	Name	Type	Description
Input	`config_path`	`pathlib.Path`	Path to a JSON configuration file (e.g., `langgraph.json`)
Output	return	`Config`	Validated configuration dictionary with defaults applied
Raises	`click.UsageError`		If the JSON is malformed, required fields are missing, version constraints are violated, or `package.json` engines are incompatible

validate_config

Direction	Name	Type	Description
Input	`config`	`Config`	Raw configuration dictionary
Output	return	`Config`	Validated and normalized configuration dictionary
Raises	`click.UsageError`		If validation fails (missing graphs, invalid versions, invalid distro, etc.)
Raises	`ValueError`		If `auth.path`, `encryption.path`, `http.app` format is invalid, or `keep_pkg_tools` entries are invalid

Usage Examples

Loading and Validating a Configuration File

import pathlib
from langgraph_cli.config import validate_config_file

config_path = pathlib.Path("langgraph.json")
config = validate_config_file(config_path)

print(config["python_version"])  # "3.11"
print(config["graphs"])          # {"my_agent": "./agent.py:graph"}

Validating a Configuration Dictionary Directly

from langgraph_cli.config import validate_config

raw_config = {
    "dependencies": ["langchain_openai", "."],
    "graphs": {"agent": "./agent.py:graph"},
    "env": {},
}

validated = validate_config(raw_config)
# validated now has defaults applied:
# python_version="3.11", node_version=None, image_distro="debian", etc.

Handling Validation Errors

import click
from langgraph_cli.config import validate_config

try:
    validate_config({
        "dependencies": [],
        "graphs": {},
    })
except click.UsageError as e:
    print(f"Configuration error: {e}")
    # "No graphs found in config. Add at least one graph to 'graphs' dictionary."

Related Pages

• Langchain_ai_Langgraph_Project_Configuration
• Environment:Langchain_ai_Langgraph_Docker_Deployment_Environment
• Langchain_ai_Langgraph_Config_Graph_Paths
• Langchain_ai_Langgraph_Langgraph_Build_Command