What this does

Debugging LangChain chains involves inspecting intermediate outputs, tracing token usage, and visualizing the execution graph to identify where a chain fails or produces incorrect results.

Steps

Enable verbose mode. Set verbose=True on the chain to print all intermediate steps.

from langchain_ollama import ChatOllama
from langchain.prompts import ChatPromptTemplate
from langchain.schema.output_parser import StrOutputParser

llm = ChatOllama(model="llama3.2", temperature=0, verbose=True)
prompt = ChatPromptTemplate.from_template("Answer: {question}")
chain = prompt | llm | StrOutputParser()

result = chain.invoke({"question": "What is 2+2?"})
# Verbose output shows prompt text, model response, and parsed result

Use RunnablePassthrough to inspect intermediate values. Insert passthrough points to log data flowing through the chain.

from langchain.schema.runnable import RunnablePassthrough

def debug_hook(x):
    print(f"[DEBUG] step input keys: {list(x.keys())}")
    return x

chain = (
    RunnablePassthrough.assign(debug=debug_hook)
    | prompt
    | llm
    | StrOutputParser()
)

Set LangChain debug environment variable. This enables trace logging globally.

import os
os.environ["LANGCHAIN_DEBUG"] = "true"

# Now all chains in this session log full execution details

Use langchain.globals.set_debug() for programmatic control.

from langchain.globals import set_debug
set_debug(True)

Capture callbacks. Use ConsoleCallbackHandler to see per-token output.

from langchain.callbacks import ConsoleCallbackHandler

chain.invoke(
    {"question": "Explain debugging."},
    config={"callbacks": [ConsoleCallbackHandler()]}
)

Verification

python -c "
from langchain.globals import set_debug, get_debug
set_debug(True)
print(get_debug())
# Expected: True
"

Common failures

Verbose mode outputs to stderr. It may be hidden in Jupyter notebooks or log aggregators. Redirect stderr or use callback handlers instead.
LangChainDebug environment variable not picked up. Must be set before importing langchain. Use set_debug(True) after import for reliability.
Callback handler slows execution significantly. Each callback fires for every token. Use sparingly in production.
Version mismatch - The installed package or runtime differs from the command shown; check the version first and rerun the smallest verification command.
Local environment drift - Another service, virtual environment, model, or path is being used; print the active binary path and configuration before changing the guide steps.

Related guides

How to Add Streaming to LangChain Chains
How to Create Basic LangChain Chains with LCEL