Langchain/Langgraph Integration Docs

[thapar25]

Description

As per the documentation, an attempt to trace Langgraph flows fails with langfuse-sdk=4.0.0 and the self-hosted image v2.

The quick-start documentation for self-hosting Langfuse doesn't specify that the latest Python SDK requires the langfuse/langfuse:3 Docker image (or later). Using langfuse/langfuse:2 results in cryptic 404 errors.

Environment

Docker Image: langfuse/langfuse:2
Python SDK: Latest from PyPI (pip install langfuse)
Framework: LangChain with LangGraph
OS: Windows

Steps to Reproduce

1. Run Langfuse v2 Docker container:

docker run -d -p 3000:3000 langfuse/langfuse:2

2. Initialize Langfuse client:

from langfuse import Langfuse
from langfuse.langchain import CallbackHandler
from langchain_core.globals import set_debug
from langchain.agents import create_agent

set_debug(True)

langfuse = Langfuse(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    base_url="http://localhost:3000"
)

langfuse_handler = CallbackHandler()

agent = create_agent(name="scratchpad", model=make_main_llm())

response = agent.invoke(
    {"messages": [{"role": "user", "content": "Test message"}]},
    config={"callbacks": [langfuse_handler]}
)

Actual Behavior

2026-03-18 01:20:44,181 - langfuse - DEBUG - Trace: Processing span name='ChatOpenRouter'
2026-03-18 01:20:44,643 - opentelemetry.exporter.otlp.proto.http.trace_exporter - ERROR - Failed to export span batch code: 404, reason: Not Found

langfuse.auth_check() results in Pydantic Errors

Requested Documentation Fix

Update the self-hosting quick-start guide to:

1. Explicitly state minimum Docker image version required (v3+)
2. Add a compatibility matrix showing Python SDK versions vs Docker image versions
3. Include a clear error message explanation for this common misconfiguration

What worked

Use langfuse/langfuse:3 or later:

docker run -d -p 3000:3000 langfuse/langfuse:3

[hassiebp]

Thanks for raising this! Which Pydantic version are you using?

[thapar25]

pydantic: 2.12.5
pydantic-core: 2.41.5