LangChain の一般的なエラー

概要

最も一般的な LangChain エラーを診断し解決するための早見表です。

前提条件

• LangChain がインストール・設定されていること
• アプリケーションログへのアクセス
• LangChain 実装の理解

エラーリファレンス

認証エラー

openai.AuthenticationError: Incorrect API key provided

# 原因: 無効またはないAPI キー
# 解決方法:
import os
os.environ["OPENAI_API_KEY"] = "sk-..."  # 正しいキーを設定

# キーがロードされていることを確認
from langchain_openai import ChatOpenAI
llm = ChatOpenAI()  # キーが無効な場合はエラーが発生

anthropic.AuthenticationError: Invalid x-api-key

# 原因: Anthropic API キーが設定されていないまたは無効
# 解決方法:
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."

# または直接渡す
from langchain_anthropic import ChatAnthropic
llm = ChatAnthropic(api_key="sk-ant-...")

インポートエラー

ModuleNotFoundError: No module named 'langchain_openai'

# 原因: プロバイダーパッケージがインストールされていない
# 解決方法:
pip install langchain-openai

# 他のプロバイダーの場合:
pip install langchain-anthropic
pip install langchain-google-genai
pip install langchain-community

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

# 原因: 古いインポートパスを使用 (0.2.0 以前)
# 旧形式 (非推奨):
from langchain.chat_models import ChatOpenAI

# 新形式 (正しい):
from langchain_openai import ChatOpenAI

レート制限

openai.RateLimitError: Rate limit reached

# 原因: API リクエストが多すぎる
# 解決方法: 指数バックオフで再試行を実装
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)

# または LangChain の組み込み再試行を使用
llm = ChatOpenAI(max_retries=3)

出力パース エラー

OutputParserException: Failed to parse output

# 原因: LLM の出力が期待される形式と一致しない
# 解決方法 1: with_retry を使用
from langchain.output_parsers import RetryOutputParser

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

# 解決方法 2: 構造化出力を使用 (より信頼性が高い)
from pydantic import BaseModel

class Output(BaseModel):
    answer: str

llm_with_structure = llm.with_structured_output(Output)

ValidationError: field required

# 原因: Pydantic モデルのバリデーションが失敗
# 解決方法: フィールドをオプショナルにするか、デフォルト値を指定
from pydantic import BaseModel, Field
from typing import Optional

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

チェーンエラー

ValueError: Missing required input keys

# 原因: 入力辞書に必要な変数がない
# デバッグ:
prompt = ChatPromptTemplate.from_template("Hello {name}, you are {age}")
print(prompt.input_variables)  # ['name', 'age']

# 解決方法: すべての必要なキーを指定
chain.invoke({"name": "Alice", "age": 30})

TypeError: Expected mapping type as input

# 原因: 間違った入力型を渡している
# 誤り:
chain.invoke("hello")

# 正しい:
chain.invoke({"input": "hello"})

エージェントエラー

AgentExecutor: max iterations reached

# 原因: エージェントがループに入っている
# 解決方法: イテレーション数を増やすか、プロンプトを改善
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    max_iterations=20,  # デフォルト 15 から増加
    early_stopping_method="force"  # 最大値に達したら強制停止
)

ToolException: Tool execution failed

# 原因: ツールが例外を発生させた
# 解決方法: ツール内にエラーハンドリングを追加
@tool
def my_tool(input: str) -> str:
    """ツールの説明。"""
    try:
        # ツールのロジック
        return result
    except Exception as e:
        return f"Tool error: {str(e)}"

メモリエラー

KeyError: 'chat_history'

# 原因: メモリキーの不一致
# 解決方法: 一貫したキー名を確認
prompt = ChatPromptTemplate.from_messages([
    MessagesPlaceholder(variable_name="chat_history"),  # これと一致させる
    ("human", "{input}")
])

# 呼び出し時:
chain.invoke({
    "input": "hello",
    "chat_history": []  # プレースホルダー名と一致させる必要があります
})

デバッグのヒント

詳細モードを有効にする

import langchain
langchain.debug = True  # すべてのチェーンステップを表示

# またはコンポーネント単位で
agent_executor = AgentExecutor(verbose=True)

LangSmith でトレース

# 環境変数を設定
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "your-langsmith-key"
os.environ["LANGCHAIN_PROJECT"] = "my-project"

# すべてのチェーンが自動的にトレースされます

バージョン互換性を確認

pip show langchain langchain-core langchain-openai

# バージョンが互換性があることを確認:
# langchain >= 0.3.0
# langchain-core >= 0.3.0
# langchain-openai >= 0.2.0

リソース

• LangChain トラブルシューティング
• LangSmith デバッグ
• GitHub Issues

次のステップ

複雑なデバッグの場合は、langchain-debug-bundle を使用して証拠を収集します。