`api_version` field in `langgraph.json` is not respected by `@langchain/langgraph-cli`

[jessieibarra]

Checked other resources

• I added a very descriptive title to this issue.
• I searched the LangGraph.js documentation with the integrated search.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangGraph.js rather than my code.
• The bug is not resolved by updating to the latest stable version of LangGraph (or the specific integration package).

Example Code

1. Create a TypeScript LangGraph project with this langgraph.json:

{
  "api_version": "0.6.39",
  "graphs": {
    "supervisor_graph": "./src/graphs/supervisorGraph.ts:app"
  },
  "node_version": "22",
  "env": "./.env",
  "dependencies": ["."]
}

2. Build with the JS CLI:

npx @langchain/langgraph-cli build -c langgraph.json

3. Inspect the built image or run it and check logs.

Expected: Base image langchain/langgraphjs-api:0.6.39-node22, logs show langgraph_api_version=0.6.39
Actual: Base image langchain/langgraphjs-api:22 (resolving to latest), logs show langgraph_api_version=0.7.28

Error Message and Stack Trace (if applicable)

No response

Description

Note: Claude Opus wrote this

Users cannot pin a specific API server version when building TypeScript graphs with the JS CLI. This is a parity gap with the Python CLI, which correctly respects api_version for both Python and TypeScript projects.

Root Cause

Two locations in @langchain/langgraph-cli need changes:

1. src/utils/config.mts — BaseConfigSchema Zod schema does not include api_version:

// Current: no api_version field
const BaseConfigSchema = z.object({
  // ...
  _INTERNAL_docker_tag: z.string().optional(),
  // ...
});

2. src/docker/docker.mts — getBaseImage() does not use api_version when constructing the image tag:

// Current: falls back to node_version, ignoring api_version
export function getBaseImage(config: Config) {
  if ("node_version" in config) {
    return `langchain/langgraphjs-api:${
      config._INTERNAL_docker_tag || config.node_version
    }`;
  }
  // ...
}

Suggested Fix

1. Add api_version to the Zod schema:

api_version: z.string().optional(),

2. Update getBaseImage() to use it:

export function getBaseImage(config: Config) {
  if ("node_version" in config) {
    const tag = config._INTERNAL_docker_tag
      || (config.api_version ? `${config.api_version}-node${config.node_version}` : config.node_version);
    return `langchain/langgraphjs-api:${tag}`;
  }
  // ...
}

System Info

Node version: v25.2.1
Operating system: darwin arm64
Package manager: npm
Package manager version: N/A

@langchain/core -> @1.1.16, , @"^1.1.16", @"^1.0.1", @"^1.1.15"
langsmith -> @0.4.8, , @"^0.4.8", @">=0.4.0
zod -> @4.3.6, , @"^3.25.76, @"^3.25.32
@langchain/langgraph -> @1.1.1, , @"^1.1.1"
@langchain/langgraph-checkpoint -> @1.0.0, , @"^1.0.0"
@langchain/langgraph-sdk -> @1.5.5, , @"~1.5.5"