LangGraph 1.0 was officially released on October 17, 2025, marking a significant milestone for the low-level agent orchestration framework. This guide walks through our real-world upgrade from LangGraph 0.3.1 to 1.0.0, including all the challenges we faced and how we solved them.
TL;DR: If your code already uses Annotation.Root, you're 90% ready for LangGraph 1.0. The main work involves updating dependencies and handling Zod v4 breaking changes.
LangGraph 1.0 is a stability-focused release with no breaking changes for code using modern patterns. The key improvements include:
Before starting, verify your current implementation:
# Check current versions
npm list @langchain/langgraph @langchain/core @langchain/openai zod
# Check if you're using Annotation.Root (the modern pattern)
grep -r "Annotation.Root" src/
If you see Annotation.Root in your graphs, you're already using 1.0-compatible patterns! 🎉
Before Upgrade:
@langchain/langgraph: 0.3.1@langchain/core: 0.3.57@langchain/openai: 0.3.17zod: 3.23.8openai: 4.29.2After Upgrade:
@langchain/langgraph: 1.0.0@langchain/core: 1.0.1@langchain/openai: 1.0.0zod: 4.1.12openai: 6.6.0First, update your package.json:
{
"dependencies": {
"@langchain/core": "^1.0.1",
"@langchain/langgraph": "^1.0.0",
"@langchain/openai": "^1.0.0",
"zod": "^4.1.12",
"openai": "^6.6.0"
}
}
Then install:
npm install
Expected Issue: You'll likely see peer dependency warnings. Don't worry—we'll resolve these.
This was the biggest challenge in our upgrade. Zod v4 renamed the errors property to issues.
Before (Zod v3):
const validation = schema.safeParse(data);
if (!validation.success) {
const errorMessage = validation.error.errors[0].message;
toast.error(errorMessage);
}
After (Zod v4):
const validation = schema.safeParse(data);
if (!validation.success) {
const errorMessage = validation.error.issues[0].message;
toast.error(errorMessage);
}
Bulk Fix Command:
# Find all instances
grep -r "\.error\.errors" src/ --include="*.ts" --include="*.tsx"
# Replace them all (macOS)
find src -name "*.tsx" -o -name "*.ts" | xargs sed -i '' 's/\.error\.errors\[/\.error\.issues\[/g'
# Replace them all (Linux)
find src -name "*.tsx" -o -name "*.ts" | xargs sed -i 's/\.error\.errors\[/\.error\.issues\[/g'
Files we updated: 21 files across form validation and API error handling.
The good news: no code changes needed if you're already using Annotation.Root!
Example of 1.0-compatible code:
import { Annotation, StateGraph } from "@langchain/langgraph";
// This pattern is LangGraph 1.0 compatible
const GraphAnnotation = Annotation.Root({
messages: Annotation<BaseMessage[]>({
reducer: (current, update) => [...current, ...update],
default: () => [],
}),
productName: Annotation<string>({
reducer: (_, update) => update ?? "",
default: () => "",
}),
});
// Extract type for use in nodes
type GraphState = typeof GraphAnnotation.State;
// Create graph (no changes needed)
const workflow = new StateGraph(GraphAnnotation)
.addNode("process", processNode)
.addNode("analyze", analyzeNode)
.addEdge("__start__", "process")
.addEdge("process", "analyze")
.addEdge("analyze", "__end__");
const graph = workflow.compile();
Old Pattern (Don't use this):
// ❌ This is the OLD pattern
import { StateGraph, StateGraphArgs } from "@langchain/langgraph";
interface WorkflowState {
messages: BaseMessage[];
}
const stateChannels: StateGraphArgs<WorkflowState>["channels"] = {
messages: {
reducer: (current, update) => current.concat(update),
default: () => [],
},
};
const workflow = new StateGraph<WorkflowState>({ channels: stateChannels });
If you're using a custom OpenAI router (like Requesty or OpenRouter), you'll need to update your fetch wrapper.
Before (OpenAI SDK v4):
export function getLangChainConfig() {
return {
openAIApiKey: process.env.API_KEY,
configuration: {
baseURL: process.env.BASE_URL,
fetch: async (url: string, init: any) => {
// Custom fetch logic
return fetch(url, init);
}
}
};
}
After (OpenAI SDK v6 + LangChain v1):
export function getLangChainConfig() {
return {
apiKey: process.env.API_KEY, // Changed from openAIApiKey
configuration: {
baseURL: process.env.BASE_URL,
// Updated fetch signature
fetch: async (url: RequestInfo | URL, init?: RequestInit) => {
// Custom fetch logic with proper types
return fetch(url, init);
}
}
};
}
Key changes:
openAIApiKey → apiKey(url: string, init: any) → (url: RequestInfo | URL, init?: RequestInit)# Run unit tests
npm test
# Check TypeScript compilation
npx tsc --noEmit
# Run production build
npm run build
Our Results:
Symptom:
npm error invalid: @langchain/core@1.0.1 (peer dependency conflict)
Solution: Check peer dependencies for all packages:
npm view @langchain/langgraph@1.0.0 peerDependencies
Ensure openai package supports Zod v4:
npm install openai@^6.6.0
OpenAI SDK v6.6.0+ supports Zod ^3.25 || ^4.0.
Symptom:
Warning: React Hook useEffect has a missing dependency: 'handleFiles'
Solution:
Wrap the function in useCallback:
import { useCallback } from "react";
const handleFiles = useCallback((files: File[]) => {
// Your logic here
}, [/* dependencies */]);
useEffect(() => {
// Now safe to use handleFiles
}, [handleFiles]);
Symptom:
TypeError: Cannot read property 'errors' of undefined
Solution:
You missed some instances. Search for remaining .errors references:
grep -rn "\.error\.errors" src/
Symptom: Getting 403 errors from OpenRouter/Requesty after upgrade.
Solution:
Update your custom fetch wrapper for OpenAI SDK v6 compatibility. Use proper Headers object:
const customFetch = async (url: RequestInfo | URL, init?: RequestInit) => {
const headers = new Headers(init?.headers);
headers.delete('content-length'); // Let fetch recalculate
return fetch(url, {
...init,
headers,
});
};
We used specialized QA agents to validate the upgrade:
Screenshot-obsessed QA that requires visual proof:
Automated code quality checks:
Results: Production-ready with 4 minor cleanup items (deprecated configs, legacy test files).
Before vs After:
Conclusion: Zero performance regression.
After the core upgrade, we addressed these quality improvements:
# .npmrc
# Comment out deprecated options
# public-hoist-pattern[]=*prisma*
rm test-kosher-catcher.js # Old CommonJS test file
Create test-langgraph-integration.js:
import { runGraph } from './src/libs/myGraph.ts';
async function testGraphExecution() {
const result = await runGraph({ input: "test" });
console.assert(result !== null, "Graph should return result");
console.log("✅ Integration test passed");
}
testGraphExecution();
// ✅ Good
const GraphAnnotation = Annotation.Root({
field: Annotation<string>({
reducer: (x, y) => y ?? x,
default: () => "",
}),
});
// ❌ Avoid
const stateChannels = { field: null };
type GraphState = typeof GraphAnnotation.State;
async function myNode(state: GraphState): Promise<Partial<GraphState>> {
// Fully typed!
return { field: state.field.toUpperCase() };
}
const GraphAnnotation = Annotation.Root({
// Arrays: accumulate
messages: Annotation<BaseMessage[]>({
reducer: (current, update) => [...current, ...update],
default: () => [],
}),
// Objects: merge
analysis: Annotation<{ status: string; data: any }>({
reducer: (current, update) => ({ ...current, ...update }),
default: () => ({ status: "pending", data: null }),
}),
// Primitives: replace (no reducer needed)
simpleValue: Annotation<string>({
default: () => "",
}),
});
const graph = workflow.compile();
// Stream events
const stream = graph.streamEvents(input, {
version: "v2",
});
for await (const event of stream) {
if (event.event === "on_chat_model_stream") {
console.log(event.data.chunk.content);
}
}
Use this checklist for your upgrade:
npm install.errors → .issues)Annotation.Root patternnpx tsc --noEmit (fix TypeScript errors)npm test (ensure 100% pass rate)npm run build (verify clean build)Our LangGraph 1.0 upgrade was successful with:
The key to a smooth upgrade is:
Annotation.Root patternFinal verdict: LangGraph 1.0 is production-ready and worth upgrading to. The framework is more stable, better typed, and fully compatible with modern LangChain tooling.
This upgrade was performed on October 21, 2025, for the Always Cool AI platform. Our codebase includes:
Questions or issues with your upgrade? Feel free to reference this guide or reach out to the LangGraph community for support.
Last updated: October 21, 2025
Share This Post:
As large language models (LLMs) become increasingly integrated into our digital infrastructure, new security vulnerabilities continue to emerge. Recent research has uncovered sophisticated attack...
Effective technical communication often requires visual representation of complex concepts. Always Cool AI's blog platform now supports Mermaid diagrams, allowing you to embed flowcharts, sequence...