langchain-ai / langchain-ai/langgraph

`add_conditional_edges` type signature causes incompatibility with dict[str, str]

Open Beginner friendly
#6,540 3 comments 0 reactions 0 assignees View on GitHub
bug external pending
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.