How to Fix 'intermittent 500 errors during development' in LangGraph (Python)

Intermittent 500 errors in LangGraph usually mean your graph is throwing an exception somewhere in the request path, but only for certain inputs or execution orders. In development, this often shows up after a few successful runs, then suddenly fails when a node returns an unexpected shape, a shared client breaks under concurrency, or a tool call raises an uncaught exception.

The key thing: 500 is the HTTP symptom. The real bug is almost always inside your graph state, node return values, async handling, or external dependency.

The Most Common Cause

The #1 cause I see is a node returning the wrong state shape or mutating state inconsistently.

LangGraph expects node functions to return a partial state update that matches your schema. If one branch returns None, a plain string, or a dict with the wrong keys, you’ll get runtime failures like:

• •TypeError: 'NoneType' object is not subscriptable
• •langgraph.errors.InvalidUpdateError: Expected dict, got ...
• •KeyError: 'messages'

Broken vs fixed pattern

# BROKEN
from typing import TypedDict, List
from langgraph.graph import StateGraph, END

class State(TypedDict):
    messages: List[str]
    status: str

def classify(state: State):
    if "urgent" in state["messages"][-1]:
        return {"status": "priority"}
    # BUG: returns None on some paths
    if "spam" in state["messages"][-1]:
        return None

builder = StateGraph(State)
builder.add_node("classify", classify)
builder.set_entry_point("classify")
builder.add_edge("classify", END)
graph = builder.compile()

# FIXED
from typing import TypedDict, List
from langgraph.graph import StateGraph, END

class State(TypedDict):
    messages: List[str]
    status: str

def classify(state: State):
    last_msg = state["messages"][-1]

    if "urgent" in last_msg:
        return {"status": "priority"}

    if "spam" in last_msg:
        return {"status": "blocked"}

    return {"status": "normal"}

builder = StateGraph(State)
builder.add_node("classify", classify)
builder.set_entry_point("classify")
builder.add_edge("classify", END)
graph = builder.compile()

If you’re using message-based graphs, also make sure you append messages through the expected reducer pattern instead of replacing the whole list accidentally.

Other Possible Causes

1) Unhandled exceptions from tools or model calls

A tool timeout or provider error will bubble up as a 500 unless you catch it inside the node.

def fetch_customer(state):
    data = crm_client.get_customer(state["customer_id"])  # may raise TimeoutError
    return {"customer": data}

Fix it by wrapping external calls and returning an error field instead of crashing the graph.

def fetch_customer(state):
    try:
        data = crm_client.get_customer(state["customer_id"])
        return {"customer": data, "error": None}
    except Exception as e:
        return {"customer": None, "error": str(e)}

2) Async/sync mismatch

If you define an async node but call blocking code inside it, or compile/run it incorrectly, requests can hang and fail intermittently.

async def enrich(state):
    result = slow_sync_function()  # blocks event loop
    return {"result": result}

Use proper async clients or offload blocking work.

import asyncio

async def enrich(state):
    result = await asyncio.to_thread(slow_sync_function)
    return {"result": result}

3) Shared mutable globals

This is common when developers keep one client or cache object at module scope and mutate it across requests. Under concurrent dev traffic, you get race conditions and random 500s.

session_history = []

def node(state):
    session_history.append(state["messages"][-1])  # shared across requests
    return {"history": session_history}

Use request-scoped state only.

def node(state):
    history = list(state.get("history", []))
    history.append(state["messages"][-1])
    return {"history": history}

4) Bad routing logic in conditional edges

If your router returns a label that doesn’t match any edge path, LangGraph can fail during execution with routing errors.

def route(state):
    return "escalatee"  # typo

builder.add_conditional_edges("router", route, {
    "escalate": "human_review",
    "done": END,
})

Make sure all route values are covered exactly.

def route(state):
    if state["risk"] > 7:
        return "escalate"
    return "done"

How to Debug It

1. •

   Run the graph directly in Python before hitting your API

   • •Call graph.invoke() with one failing payload.
   • •If it throws langgraph.errors.InvalidUpdateError or KeyError, you’ve found a graph-level issue.
2. •

   Print every node input and output

   • •Add temporary logs inside each node.
   • •Confirm every node returns a dict and that required keys exist.
3. •

   Isolate external dependencies

   • •Replace LLM/tool calls with hardcoded responses.
   • •If the 500 disappears, the bug is likely timeout, auth failure, or provider response parsing.
4. •

   Test concurrency

   • •Hit the endpoint with multiple parallel requests.
   • •If failures increase under load, check for shared globals, mutable caches, or non-thread-safe clients.

Prevention

• •

  Keep node outputs strict and explicit.

  • •Return only partial state dicts.
  • •Validate shapes early with Pydantic or TypedDict discipline.
• •

  Wrap every external call.

  • •Tools, vector DBs, HTTP APIs, and LLM calls should fail into controlled error fields.
  • •Don’t let raw exceptions escape nodes unless you want a hard failure.
• •

  Avoid module-level mutable state.

  • •Put request-specific data into graph state.
  • •Treat nodes as pure functions whenever possible.

If you’re still seeing intermittent 500 errors after checking these areas, inspect the exact traceback from your LangGraph runtime. In practice, the stack trace usually points straight at either InvalidUpdateError, a bad router label, or an uncaught exception inside one node.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.