10 Real-World LangGraph Production Pitfalls That Can Crash Your App

1. Thread ID Misused as User ID

Using the user identifier directly as thread_id makes all conversations of that user share a single state snapshot. Each invoke call appends to the same snapshot, so a second conversation inherits the first conversation’s memory and can even mix replies from other users.

// ❌ Wrong: user ID used as thread_id, state accumulates permanently
const result = await graph.invoke({ messages: [new HumanMessage(input)] }, { configurable: { thread_id: userId } });

// ✅ Correct: generate a unique thread_id per conversation
import { v4 as uuidv4 } from 'uuid';
async function startNewConversation(userId, input) {
  const threadId = `${userId}-${uuidv4()}`; // user ID + unique uuid
  await db.saveThread({ userId, threadId, createdAt: new Date() });
  return await graph.invoke({ messages: [new HumanMessage(input)] }, { configurable: { thread_id: threadId } });
}

Wrong usage: thread_id = userId (single thread per user, state never resets)

Correct usage: thread_id = userId + "-" + uuid() (new thread per conversation, archive old state)

2. State Bloats: Unlimited Message List & Large Objects

Heavy users can cause token consumption to explode when the entire message history is sent to the model each turn. Storing large binary files or full API responses in the state makes checkpoint writes increasingly slow.

// ✅ Trim message history at node entry (recommended)
async function chatNode(state) {
  const trimmedMessages = trimMessages(state.messages, {
    maxTokens: 4000,
    strategy: "last",
    tokenCounter: model,
    includeSystem: true,
  });
  const response = await model.invoke(trimmedMessages);
  return { messages: [response] };
}

// ✅ Store only references for large objects
const GoodState = Annotation.Root({
  messages: Annotation<BaseMessage[]>({ reducer: messagesStateReducer, default: () => [] }),
  fileRef: Annotation<string>({ default: () => '' }), // store S3 key only
  apiResponseSummary: Annotation<string>({ default: () => '' }), // store summary only
});

State should contain: message list with window limit, key metadata (ID, status flags), references (URL, S3 key)

State should not contain: binary file content, full raw API response, large nested JSON

3. Tool Errors Crash the Graph: No Fallback Node

If an external API times out, the exception bubbles up, returning a 500 to the user and leaving no log. Subsequent retries can re‑enter the failing tool, causing a loop.

// ✅ Capture errors in the tool layer and return a structured result
const searchTool = tool(async ({ query }) => {
  try {
    const result = await Promise.race([
      externalApi.search(query),
      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 5000))
    ]);
    return JSON.stringify({ success: true, data: result.data });
  } catch (err) {
    // Do not throw; let the LLM perceive the error
    return JSON.stringify({ success: false, error: err.message, suggestion: "try rephrasing or use fallback" });
  }
}, { name: "search", schema: z.object({ query: z.string() }) });

// State adds error counting; after 3 failures route to a downgrade node
const StateAnnotation = Annotation.Root({
  messages: Annotation<BaseMessage[]>({ reducer: messagesStateReducer, default: () => [] }),
  errorCount: Annotation<number>({ reducer: (a, b) => a + b, default: () => 0 }),
});
function routeAfterTools(state) {
  if (state.errorCount >= 3) return "error_handler";
  return "agent";
}

4. Conditional Routing Loops & Concurrent Thread Conflicts

Complex queries can trap the LLM in a loop that repeatedly calls the same tool, exhausting quota. Simultaneous requests using the same thread_id cause checkpoint version conflicts.

// ✅ Loop protection: add iteration counter, enforce exit, set framework recursion limit
const StateAnnotation = Annotation.Root({
  messages: Annotation<BaseMessage[]>({ reducer: messagesStateReducer, default: () => [] }),
  iterationCount: Annotation<number>({ reducer: (a, b) => a + b, default: () => 0 }),
});
async function agentNode(state) {
  const response = await model.bindTools(tools).invoke(state.messages);
  return { messages: [response], iterationCount: state.iterationCount + 1 };
}
function routeAgent(state) {
  if (state.iterationCount >= 10) return "END"; // force exit after 10 loops
  return state.messages.at(-1)?.tool_calls?.length ? "tools" : "END";
}
// Framework‑level recursion limit example
const result = await app.invoke(input, { configurable: { thread_id: threadId }, recursionLimit: 25 });

// ✅ Concurrency protection: per‑thread mutex
const threadLocks = new Map();
function getThreadLock(threadId) {
  if (!threadLocks.has(threadId)) threadLocks.set(threadId, new Mutex());
  return threadLocks.get(threadId);
}
async function handleUserMessage(threadId, input) {
  return getThreadLock(threadId).runExclusive(async () =>
    graph.invoke({ messages: [new HumanMessage(input)] }, { configurable: { thread_id: threadId } })
  );
}

5. SubGraph State Mismatch: Silent Data Loss

If a SubGraph outputs a field name that the parent Graph does not declare, the data disappears without error.

// ❌ Bad: SubGraph returns "result" which parent Graph lacks
const SubGraphStateBad = Annotation.Root({
  input: Annotation<string>({ default: () => '' }),
  result: Annotation<string>({ default: () => '' }), // ← parent has no "result"
});

// ✅ Good: SubGraph uses the exact field name expected by the parent
const ParentState = Annotation.Root({
  messages: Annotation<BaseMessage[]>({ reducer: messagesStateReducer, default: () => [] }),
  finalAnswer: Annotation<string>({ default: () => '' }), // matches parent field
  internalSteps: Annotation<string[]>({ reducer: (a, b) => [...a, ...b], default: () => [] }),
});
const SubGraphStateGood = Annotation.Root({
  messages: Annotation<BaseMessage[]>({ reducer: messagesStateReducer, default: () => [] }),
  finalAnswer: Annotation<string>({ default: () => '' }), // aligned with parent
  internalSteps: Annotation<string[]>({ reducer: (a, b) => [...a, ...b], default: () => [] }),
});

6. Human‑in‑the‑Loop Timeout: Graph State Stuck

Interrupted checkpoints remain in the database indefinitely. If a user later confirms the stale action, business logic breaks.

// ✅ Record interruption time and auto‑cancel after timeout
const StateAnnotation = Annotation.Root({
  messages: Annotation<BaseMessage[]>({ reducer: messagesStateReducer, default: () => [] }),
  interruptedAt: Annotation<number | null>({ default: () => null }),
  interruptTimeoutMs: Annotation<number>({ default: () => 30 * 60 * 1000 }), // 30 min
});
async function reviewNode(state) {
  if (state.interruptedAt) {
    const elapsed = Date.now() - state.interruptedAt;
    if (elapsed > state.interruptTimeoutMs) {
      return { messages: [new AIMessage("Operation timed out, automatically cancelled.")], interruptedAt: null };
    }
  }
  if (!state.interruptedAt) {
    return { interruptedAt: Date.now() }; // record first interruption
  }
  const userInput = await interrupt({ message: "Please confirm action: " + state.pendingAction });
  return { approvedAction: userInput, interruptedAt: null };
}

7. Production Checkpointer Misconfiguration

Leaving LANGCHAIN_TRACING_V2=true on in production sends all user data to LangSmith, exposing PII. Using MemorySaver causes the entire conversation history to disappear on process restart.

// ❌ Common production misconfigurations
// LANGCHAIN_TRACING_V2=true   ← leaks all user data to LangSmith
// const checkpointer = new MemorySaver()   ← loses data on restart

// ✅ Correct production setup
// LANGCHAIN_TRACING_V2=false   ← disable full tracing or send only sanitized metadata
import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
const checkpointer = PostgresSaver.fromConnString(process.env.DATABASE_URL!);
await checkpointer.setup(); // one‑time initialization
const app = graph.compile({ checkpointer }); // persists across restarts

// If tracing is needed, send only sanitized metadata
const result = await graph.invoke(input, {
  configurable: { thread_id: threadId },
  metadata: { userId: hashUserId(userId), sessionId }, // no raw PII
});

MemorySaver : not persistent, no multi‑instance sharing – suitable only for local development or unit tests.

PostgresSaver : persistent across restarts, supports multi‑instance sharing – production preferred.

RedisSaver : persistent, supports multi‑instance sharing – good for high‑concurrency, short sessions.

SqliteSaver : persistent on a single machine, no multi‑instance sharing – suitable for single‑machine deployment.

These seven pitfalls illustrate how production‑grade LangGraph applications can fail when thread identifiers, state size, error handling, routing logic, subgraph contracts, human‑in‑the‑loop timeouts, or checkpoint configuration are not managed correctly.