langchain-ai/langgraphjs
1
0
Fork 0
mirror of https://github.com/langchain-ai/langgraphjs.git synced 2026-07-22 09:05:28 -04:00
Code Issues 108 Packages Projects Releases 20 Wiki Activity

Type System Mismatch Between Documentation and Implementation #248

New Issue
Closed
opened 2026-02-15 18:15:01 -05:00 by yindo · 2 comments
yindo commented 2026-02-15 18:15:01 -05:00
Owner
Copy Link
Copy Source

Originally created by @s3m1ck on GitHub (Apr 30, 2025).

Issue Description

The current documentation at https://langchain-ai.github.io/langgraphjs/concepts/low_level/ appears to be out of sync with the actual implementation, particularly regarding StateGraph type definitions and edge handling.

Current Behavior

When implementing a StateGraph following the documentation examples, we encounter several TypeScript errors:

  1. Node Names in Edge Definitions:
workflow.addEdge("research", "analyze");
// Error: Argument of type '"research"' is not assignable to parameter of type '"__start__" | "__start__"[]'
  1. Entry Point Setting:
workflow.setEntryPoint("decide");
// Error: Argument of type '"decide"' is not assignable to parameter of type '"__start__"'
  1. Conditional Edge Methods:
workflow.addConditionalEdge("decide", (state) => state.currentStep === "research" ? "research" : "recommend");
// Error: Property 'addConditionalEdge' does not exist on type 'StateGraph<...>'

Expected Behavior

Based on the documentation:

  • We should be able to use arbitrary string names for nodes
  • Edge definitions should accept these node names
  • Entry points should accept node names
  • Conditional edge routing should work as documented

Reproduction Steps

  1. Create a new StateGraph with Annotation
  2. Add nodes with string identifiers
  3. Attempt to add edges between nodes
  4. Set entry point

Environment

  • @langchain/langgraph: 0.2.67
  • TypeScript: 5.5.4
  • Node.js: v20.19.1

Related Issues

  • #1097: Similar type system constraints with Zod schemas
  • #1096: Type issues with addNode
  • #1131: StateGraph creation error messages

Questions

  1. What is the correct way to define edges between custom-named nodes?
  2. How should entry points be set for custom-named nodes?
  3. Is there a working example that demonstrates the current correct implementation?

Additional Context

The documentation shows a more flexible API than what TypeScript allows. Either:

  1. The documentation needs updating to reflect the current type constraints, or
  2. The type definitions need updating to match the documented behavior

This appears to be part of a broader pattern of TypeScript integration challenges, as evidenced by related issues #1097 and #1096.

Proposed Solution

Would appreciate either:

  1. Updated documentation reflecting current type constraints
  2. Updated type definitions matching documented behavior
  3. A working example demonstrating the correct pattern

Let me know if you need any additional information or clarification.

Originally created by @s3m1ck on GitHub (Apr 30, 2025). ## Issue Description The current documentation at https://langchain-ai.github.io/langgraphjs/concepts/low_level/ appears to be out of sync with the actual implementation, particularly regarding StateGraph type definitions and edge handling. ## Current Behavior When implementing a StateGraph following the documentation examples, we encounter several TypeScript errors: 1. Node Names in Edge Definitions: ```typescript workflow.addEdge("research", "analyze"); // Error: Argument of type '"research"' is not assignable to parameter of type '"__start__" | "__start__"[]' ``` 2. Entry Point Setting: ```typescript workflow.setEntryPoint("decide"); // Error: Argument of type '"decide"' is not assignable to parameter of type '"__start__"' ``` 3. Conditional Edge Methods: ```typescript workflow.addConditionalEdge("decide", (state) => state.currentStep === "research" ? "research" : "recommend"); // Error: Property 'addConditionalEdge' does not exist on type 'StateGraph<...>' ``` ## Expected Behavior Based on the documentation: - We should be able to use arbitrary string names for nodes - Edge definitions should accept these node names - Entry points should accept node names - Conditional edge routing should work as documented ## Reproduction Steps 1. Create a new StateGraph with Annotation 2. Add nodes with string identifiers 3. Attempt to add edges between nodes 4. Set entry point ## Environment - @langchain/langgraph: 0.2.67 - TypeScript: 5.5.4 - Node.js: v20.19.1 ## Related Issues - #1097: Similar type system constraints with Zod schemas - #1096: Type issues with addNode - #1131: StateGraph creation error messages ## Questions 1. What is the correct way to define edges between custom-named nodes? 2. How should entry points be set for custom-named nodes? 3. Is there a working example that demonstrates the current correct implementation? ## Additional Context The documentation shows a more flexible API than what TypeScript allows. Either: 1. The documentation needs updating to reflect the current type constraints, or 2. The type definitions need updating to match the documented behavior This appears to be part of a broader pattern of TypeScript integration challenges, as evidenced by related issues #1097 and #1096. ## Proposed Solution Would appreciate either: 1. Updated documentation reflecting current type constraints 2. Updated type definitions matching documented behavior 3. A working example demonstrating the correct pattern Let me know if you need any additional information or clarification.
yindo closed this issue 2026-02-15 18:15:01 -05:00
yindo commented 2026-02-15 18:15:03 -05:00
Author
Owner
Copy Link
Copy Source

@JotaRaffalli commented on GitHub (May 4, 2025):

I’ve been digging into this and initially thought I misread the docs, but now I’m certain there’s a mismatch in the TypeScript types. The current addEdge definition:

addEdge(startKey: typeof START | N | N[], endKey: N | typeof END): this;
…is stricter than what the documentation suggests, which is causing headaches in real usage.

@JotaRaffalli commented on GitHub (May 4, 2025): I’ve been digging into this and initially thought I misread the docs, but now I’m certain there’s a mismatch in the TypeScript types. The current addEdge definition: `addEdge(startKey: typeof START | N | N[], endKey: N | typeof END): this; ` …is stricter than what the documentation suggests, which is causing headaches in real usage.
yindo commented 2026-02-15 18:15:03 -05:00
Author
Owner
Copy Link
Copy Source

@dqbd commented on GitHub (May 19, 2025):

Hello! To ensure that the type system works properly, you need to ensure that you keep chaining the existing instance of StateGraph.

In other words, do this

// ✅ valid code
const graph = new StateGraph(...)
  .addNode("one", (state) => state)
  .addNode("two", (state) => state)
  .addEdge("__start__", "one")
  .addEdge("one", "two")
  .compile()

not this

// ❌ Invalid code
const workflow = new StateGraph(...)
workflow.addNode("one", (state) => state)
workflow.addNode("two", (state) => state)
workflow.addEdge("__start__", "one")
workflow.addEdge("one", "two")

const graph = workflow.compile()
@dqbd commented on GitHub (May 19, 2025): Hello! To ensure that the type system works properly, you need to ensure that you keep chaining the existing instance of StateGraph. In other words, do this ``` // ✅ valid code const graph = new StateGraph(...) .addNode("one", (state) => state) .addNode("two", (state) => state) .addEdge("__start__", "one") .addEdge("one", "two") .compile() ``` not this ``` // ❌ Invalid code const workflow = new StateGraph(...) workflow.addNode("one", (state) => state) workflow.addNode("two", (state) => state) workflow.addEdge("__start__", "one") workflow.addEdge("one", "two") const graph = workflow.compile() ```
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
checkpointer
docs-needed
documentation
enhancement
good first issue
good writeup
help wanted
invalid
langgraph-supervisor
open-swe-auto
platform
prebuilt
pull-request
Mirrored from GitHub Pull Request
 question
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/langgraphjs#248
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?