LangChain Common Errors

Overview

Quick reference for diagnosing and resolving the most common LangChain errors.

Prerequisites

• LangChain installed and configured

• Access to application logs

• Understanding of your LangChain implementation

Error Reference

Authentication Errors

openai.AuthenticationError: Incorrect API key provided

Cause: Invalid or missing API key

Solution:

import os os.environ["OPENAI_API_KEY"] = "sk-..." # Set correct key

Verify key is loaded

from langchain_openai import ChatOpenAI llm = ChatOpenAI() # Will raise error if key invalid

anthropic.AuthenticationError: Invalid x-api-key

Cause: Anthropic API key not set or invalid

Solution:

os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."

Or pass directly

from langchain_anthropic import ChatAnthropic llm = ChatAnthropic(api_key="sk-ant-...")

Import Errors

ModuleNotFoundError: No module named 'langchain_openai'

set -euo pipefail

Cause: Provider package not installed

Solution:

pip install langchain-openai

For other providers:

pip install langchain-anthropic pip install langchain-google-genai pip install langchain-community

ImportError: cannot import name 'ChatOpenAI' from 'langchain'

Cause: Using old import path (pre-0.2.0)

Old (deprecated):

from langchain.chat_models import ChatOpenAI

New (correct):

from langchain_openai import ChatOpenAI

Rate Limiting

openai.RateLimitError: Rate limit reached

Cause: Too many API requests

Solution: Implement retry with backoff

from langchain_openai import ChatOpenAI from tenacity import retry, wait_exponential, stop_after_attempt

@retry(wait=wait_exponential(min=1, max=60), stop=stop_after_attempt(5)) def call_with_retry(llm, prompt): return llm.invoke(prompt)

Or use LangChain's built-in retry

llm = ChatOpenAI(max_retries=3)

Output Parsing Errors

OutputParserException: Failed to parse output

Cause: LLM output doesn't match expected format

Solution 1: Use with_retry

from langchain.output_parsers import RetryOutputParser

parser = RetryOutputParser.from_llm(parser=your_parser, llm=llm)

Solution 2: Use structured output (more reliable)

from pydantic import BaseModel

class Output(BaseModel): answer: str

llm_with_structure = llm.with_structured_output(Output)

ValidationError: field required

Cause: Pydantic model validation failed

Solution: Make fields optional or provide defaults

from pydantic import BaseModel, Field from typing import Optional

class Output(BaseModel): answer: str confidence: Optional[float] = Field(default=None)

Chain Errors

ValueError: Missing required input keys

Cause: Input dict missing required variables

Debug:

prompt = ChatPromptTemplate.from_template("Hello {name}, you are {age}") print(prompt.input_variables) # ['name', 'age']

Solution: Provide all required keys

chain.invoke({"name": "Alice", "age": 30})

TypeError: Expected mapping type as input

Cause: Passing wrong input type

Wrong:

chain.invoke("hello")

Correct:

chain.invoke({"input": "hello"})

Agent Errors

AgentExecutor: max iterations reached

Cause: Agent stuck in loop

Solution: Increase iterations or improve prompts

agent_executor = AgentExecutor( agent=agent, tools=tools, max_iterations=20, # Increase from default 15 early_stopping_method="force" # Force stop after max )

ToolException: Tool execution failed

Cause: Tool raised an exception

Solution: Add error handling in tool

@tool def my_tool(input: str) -> str: """Tool description.""" try: # Tool logic return result except Exception as e: return f"Tool error: {str(e)}"

Memory Errors

KeyError: 'chat_history'

Cause: Memory key mismatch

Solution: Ensure consistent key names

prompt = ChatPromptTemplate.from_messages([ MessagesPlaceholder(variable_name="chat_history"), # Match this ("human", "{input}") ])

When invoking:

chain.invoke({ "input": "hello", "chat_history": [] # Must match placeholder name })

Debugging Tips

Enable Verbose Mode

import langchain langchain.debug = True # Shows all chain steps

Or per-component

agent_executor = AgentExecutor(verbose=True)

Trace with LangSmith

Set environment variables

os.environ["LANGCHAIN_TRACING_V2"] = "true" os.environ["LANGCHAIN_API_KEY"] = "your-langsmith-key" os.environ["LANGCHAIN_PROJECT"] = "my-project"

All chains automatically traced

Check Version Compatibility

set -euo pipefail pip show langchain langchain-core langchain-openai

Ensure versions are compatible:

langchain >= 0.3.0

langchain-core >= 0.3.0

langchain-openai >= 0.2.0

Resources

• LangChain Troubleshooting

• LangSmith Debugging

• GitHub Issues

Next Steps

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

Instructions

• Assess the current state of the debugging configuration

• Identify the specific requirements and constraints

• Apply the recommended patterns from this skill

• Validate the changes against expected behavior

• Document the configuration for team reference

Output

• Configuration files or code changes applied to the project

• Validation report confirming correct implementation

• Summary of changes made and their rationale

Error Handling

Error Cause Resolution

Authentication failure Invalid or expired credentials Refresh tokens or re-authenticate with debugging

Configuration conflict Incompatible settings detected Review and resolve conflicting parameters

Resource not found Referenced resource missing Verify resource exists and permissions are correct

Examples

Basic usage: Apply langchain common errors to a standard project setup with default configuration options.

Advanced scenario: Customize langchain common errors for production environments with multiple constraints and team-specific requirements.