langchain-common-errors
Diagnose and fix common LangChain errors and exceptions. Use when encountering LangChain errors, debugging failures, or troubleshooting integration issues. Trigger with phrases like "langchain error", "langchain exception", "debug langchain", "langchain not working", "langchain troubleshoot".
- License 许可
- MIT
- 最近更新
- 2026-05-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- langchain-common-errors
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- Diagnose and fix common LangChain errors and exceptions. Use when encountering LangChain errors, debugging failures, or troubleshooting integration issues. Trigger with phrases like "langchain error", "langchain exception", "debug langchain", "langchain not working", "langchain troubleshoot".
- allowed-tools
- Read, Write, Edit, Grep
- compatible-with
- claude-code, codex, openclaw
03 SKILL.md 正文
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
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.
04 同仓库更多 Skills
zustand-store-ts
Create Zustand stores with TypeScript, subscribeWithSelector middleware, and proper state/action separation. Use when building React state management, creating global stores, or implementing reactive state patterns with Zustand.
zustand-store-creator
Zustand Store Creator - Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category.
zero-trust-config-helper
Zero Trust Config Helper - Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category.
zapier-integration-helper
Zapier Integration Helper - Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category.
zai-cli
Execute z.AI CLI providing vision, search, reader, and GitHub exploration via CLI and MCP. Use when user needs image/video analysis, OCR, UI-to-code conversion, error diagnosis, real-time web search, web page to markdown extraction, or GitHub code exploration. Trigger with phrases like "analyze this image", "search the web for", "read this page", "explore this repo", or "use zai". Requires Z_AI_API_KEY.
yt-research
Research competitor YouTube channels, niches, and trending topics for your content strategy. Use this skill whenever the user says "research channels", "analyze competitors", "find trending topics", "niche analysis", "competitive research", "what are other creators doing", "scrape YouTube channels", or wants to understand the competitive landscape for a specific tool or topic area. Use when working with yt research. Trigger with 'yt', 'research'.