langchain-common-errors

name	langchain-common-errors
description	Diagnose and fix common LangChain errors and exceptions. Use when this capability is needed.
metadata	{"author":"flight505"}

LangChain Common Errors

Overview

Quick reference for the most frequent LangChain errors with exact error messages, root causes, and copy-paste fixes.

Import Errors

Cannot find module '@langchain/openai'

# Provider package not installed
npm install @langchain/openai
# Also: @langchain/anthropic, @langchain/google-genai, @langchain/community

Cannot import name 'ChatOpenAI' from 'langchain' (Python)

# Old import path (pre-0.2). Use provider packages:
# OLD: from langchain.chat_models import ChatOpenAI
# NEW:
from langchain_openai import ChatOpenAI

@langchain/core version mismatch

# All @langchain/* packages must share the same minor version
npm ls @langchain/core
# Fix: update all together
npm install @langchain/core@latest @langchain/openai@latest @langchain/anthropic@latest

Authentication Errors

AuthenticationError: Incorrect API key provided

// Key not set or wrong format
// Check:
console.log("Key present:", !!process.env.OPENAI_API_KEY);
console.log("Key prefix:", process.env.OPENAI_API_KEY?.slice(0, 7));
// Should be "sk-..." for OpenAI, "sk-ant-..." for Anthropic

// Fix: ensure dotenv is loaded BEFORE imports
import "dotenv/config";
import { ChatOpenAI } from "@langchain/openai";

Error: OPENAI_API_KEY is not set

// Model constructor can't find the key
// Option 1: environment variable
process.env.OPENAI_API_KEY = "sk-...";

// Option 2: pass directly (not recommended for production)
const model = new ChatOpenAI({
  model: "gpt-4o-mini",
  apiKey: "sk-...",
});

Chain Errors

Missing value for input variable "topic"

// Template has variables not provided in invoke()
const prompt = ChatPromptTemplate.fromTemplate("Tell me about {topic} in {language}");
console.log(prompt.inputVariables); // ["topic", "language"]

// Fix: provide ALL variables
await chain.invoke({ topic: "AI", language: "English" }); // not just { topic: "AI" }

Expected mapping type as input to ChatPromptTemplate

// Passing a string instead of an object
// WRONG:
await chain.invoke("hello");

// RIGHT:
await chain.invoke({ input: "hello" });

Output Parsing Errors

OutputParserException: Failed to parse

// LLM output doesn't match expected format
// Fix 1: Use withStructuredOutput (most reliable)
import { z } from "zod";

const schema = z.object({
  answer: z.string(),
  confidence: z.number().optional(), // make fields optional for resilience
});
const structuredModel = model.withStructuredOutput(schema);

// Fix 2: Add retry parser (Python)
// from langchain.output_parsers import RetryWithErrorOutputParser
// retry_parser = RetryWithErrorOutputParser.from_llm(parser=parser, llm=llm)

ZodError: validation failed

// Structured output doesn't match Zod schema
// Fix: make optional fields nullable, add defaults
const Schema = z.object({
  answer: z.string(),
  confidence: z.number().min(0).max(1).default(0.5),
  sources: z.array(z.string()).default([]),
});

Agent Errors

AgentExecutor: max iterations reached

// Agent stuck in a tool-calling loop
const executor = new AgentExecutor({
  agent,
  tools,
  maxIterations: 15,          // increase from default 10
  earlyStoppingMethod: "force", // force stop instead of error
});

// Root cause: usually a vague system prompt. Be specific about when to stop.

Missing placeholder 'agent_scratchpad'

// Agent prompt MUST include the scratchpad placeholder
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are helpful."],
  ["human", "{input}"],
  new MessagesPlaceholder("agent_scratchpad"),  // REQUIRED
]);

Rate Limiting

429 Too Many Requests / RateLimitError

// Built-in retry handles this automatically
const model = new ChatOpenAI({
  model: "gpt-4o-mini",
  maxRetries: 5,    // exponential backoff on 429
});

// For batch processing, control concurrency
const results = await chain.batch(inputs, { maxConcurrency: 5 });

Memory/History Errors

KeyError: 'chat_history'

// MessagesPlaceholder name must match invoke key
const prompt = ChatPromptTemplate.fromMessages([
  new MessagesPlaceholder("chat_history"),  // this name...
  ["human", "{input}"],
]);

await chain.invoke({
  input: "hello",
  chat_history: [],  // ...must match this key
});

Debugging Toolkit

Enable Debug Logging

// See every step in chain execution
import { setVerbose } from "@langchain/core";
setVerbose(true);  // logs all chain steps

// Python equivalent:
// import langchain; langchain.debug = True

Enable LangSmith Tracing

# Add to .env — all chains automatically traced
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=my-debug-session

Check Version Compatibility

# All @langchain/* packages should be on compatible versions
npm ls @langchain/core 2>&1 | head -20

# Python
pip show langchain langchain-core langchain-openai | grep -E "Name|Version"

Quick Diagnostic Script

import "dotenv/config";

async function diagnose() {
  const checks: Record<string, string> = {};

  // Check env vars
  checks["OPENAI_API_KEY"] = process.env.OPENAI_API_KEY ? "set" : "MISSING";
  checks["ANTHROPIC_API_KEY"] = process.env.ANTHROPIC_API_KEY ? "set" : "MISSING";

  // Check imports
  try {
    await import("@langchain/core");
    checks["@langchain/core"] = "OK";
  } catch { checks["@langchain/core"] = "MISSING"; }

  try {
    const { ChatOpenAI } = await import("@langchain/openai");
    const llm = new ChatOpenAI({ model: "gpt-4o-mini" });
    await llm.invoke("test");
    checks["OpenAI connection"] = "OK";
  } catch (e: any) {
    checks["OpenAI connection"] = e..(, );
  }

  .(checks);
}

 ();

Resources

• LangChain Troubleshooting
• LangSmith Debugging
• GitHub Issues

Next Steps

For complex debugging, use langchain-debug-bundle to collect comprehensive evidence.

---

Source: flight505/skill-forge — distributed by TomeVault.