langchain-ai / langchain-ai/langgraph
`add_conditional_edges` type signature causes incompatibility with dict[str, str]
- Dominant language
- Python
- Stars
- 41.8k
- Forks
- 7.1k
- Avg merge
- 23h 7m
- Merged PRs (30d)
- 30
Description
### Checked other resources
- [x] This is a bug, not a usage question. For questions, please use the LangChain Forum (https://forum.langchain.com/).
- [x] I added a clear and detailed title that summarizes the issue.
- [x] I read what a minimal reproducible example is (https://stackoverflow.com/help/minimal-reproducible-example).
- [x] I included a self-contained, minimal example that demonstrates the issue INCLUDING all the relevant imports. The code run AS IS to reproduce the issue.
### Example Code
```python
from typing import TypedDict
from langgraph.graph import END, StateGraph
class State(TypedDict):
approved: bool
def check_approval(state: State) -> str:
return "yes" if state["approved"] else "no"
def approved_node(state: State) -> State:
return state
def rejected_node(state: State) -> State:
return state
graph = StateGraph(State)
graph.add_node("approved", approved_node)
graph.add_node("rejected", rejected_node)
# This line causes pyright error:
# dict[str, str] is not assignable to dict[Hashable, str]
path_map: dict[str, str] = {"yes": "approved", "no": "rejected"}
graph.add_conditional_edges("__start__", check_approval, path_map)
graph.add_edge("approved", END)
graph.add_edge("rejected", END)
app = graph.compile()
```
### Error Message and Stack Trace (if applicable)
```shell
Argument of type "dict[str, str]" cannot be assigned to parameter "path_map" of type "dict[Hashable, str] | list[str] | None" in function "add_conditional_edges"
Type "dict[str, str]" is not assignable to type "dict[Hashable, str] | list[str] | None"
"dict[str, str]" is not assignable to "dict[Hashable, str]"
Type parameter "_KT@dict" is invariant, but "str" is not the same as "Hashable"
"dict[str, str]" is not assignable to "list[str]"
"dict[str, str]" is not assignable to "None" (reportArgumentType)
1 error, 0 warnings, 0 informations
```
### Description
#### Problem
The current type signature of `add_conditional_edges` uses `dict[Hashable, str]` for the `path_map` parameter:
```python
def add_conditional_edges(
self,
source: str,
path: Callable[..., str],
path_map: dict[Hashable, str] | list[str] | None = None,
) -> Self:
```
This causes a type error when passing a `dict[str, str]`:
```python
path_map: dict[str, str] = {"yes": "node_a", "no": "node_b"}
graph.add_conditional_edges("source", my_condition, path_map)
# pyright error: dict[str, str] is not assignable to dict[Hashable, str]
```
#### Why This Happens
In Python's type system, `dict` is **invariant** in its key type. Even though `str` is a subtype of `Hashable`, `dict[str, str]` is not a
subtype of `dict[Hashable, str]`.
This is by design — if it were allowed, one could insert non-`str` keys (like `int`) through a `dict[Hashable, str]` reference, breaking the
original type constraint.
#### Proposed Solution
Use a generic type parameter to link the return type of `path` with the key type of `path_map`:
```python
from typing import TypeVar
from collections.abc import Hashable
K = TypeVar("K", bound=Hashable)
def add_conditional_edges(
self,
source: str,
path: Callable[..., K],
path_map: dict[K, str] | list[str] | None = None,
) -> Self:
```
This way:
- When `path` returns `str`, `path_map` expects `dict[str, str]`
- When `path` returns an `Enum`, `path_map` expects `dict[ThatEnum, str]`
- Type safety is preserved
### System Info
System Information
------------------
> OS: Darwin
> OS Version: Darwin Kernel Version 25.1.0: Mon Oct 20 19:33:00 PDT 2025; root:xnu-12377.41.6~2/RELEASE_ARM64_T6020
> Python Version: 3.12.12 (main, Oct 31 2025, 23:21:56) [Clang 21.1.4 ]
Package Information
-------------------
> langchain_core: 1.1.1
> langsmith: 0.4.55
> langgraph_sdk: 0.2.12
Optional packages not installed
-------------------------------
> langserve
Other Dependencies
------------------
> httpx: 0.28.1
> jsonpatch: 1.33
> orjson: 3.11.4
> packaging: 25.0
> pydantic: 2.12.5
> pyyaml: 6.0.3
> requests: 2.32.5
> requests-toolbelt: 1.0.0
> tenacity: 9.1.2
> typing-extensions: 4.15.0
> uuid-utils: 0.12.0
> zstandard: 0.25.0
Contributor guide
Research direction
Start at the add_conditional_edges definition in the LangGraph source and reproduce the reported pyright error with the example in this issue. Update the type signature so a dict[str, str] matching a string-returning path is accepted, then run the relevant typing or test checks to confirm the incompatibility is resolved.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100