Troubleshooting & FAQ - Langfuse

Troubleshooting & FAQ

If you cannot find your issue below, try Ask AI, open a GitHub issue, or contact support.

Ensure LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_BASE_URL are set as environment variables or passed to Langfuse() as constructor arguments.
Use langfuse.auth_check() during setup (not in production) to confirm connectivity.

See Missing traces for common reasons and solutions.
Confirm tracing_enabled is True and sample_rate is not 0.0.
Call langfuse.shutdown() (or langfuse.flush() in short-lived jobs) so queued data is exported.
Enable debug logging (debug=True or LANGFUSE_DEBUG="True" on Python, LANGFUSE_DEBUG="true" or LANGFUSE_LOG_LEVEL="DEBUG" on JS/TS) to inspect exporter output.

Self-hosted users need Langfuse platform >= 3.63.0 for the OTel based SDKs.
Prefer context managers (with langfuse.start_as_current_observation(...)) to maintain OTEL context.
If using manual observations (langfuse.start_observation()), always call .end().
In async code, rely on Langfuse helpers to avoid losing context across await boundaries.
If an observation references a parent that Langfuse never received, it is shown at the trace root instead of under its intended parent. This can happen when the parent was filtered out, dropped, or never sent, so make sure every referenced parent observation is actually exported.

Ensure Langfuse wrappers (from langfuse.openai import openai or LangfuseCallbackHandler) are instantiated before API calls.
Check version compatibility between Langfuse, LangChain, and the model SDKs.

Use LangfuseMedia objects for audio/image payloads and inspect debug logs to surface upload errors (uploads run on background threads).

Make sure you are on @vercel/otel v2 or later. Versions before v2 were built on the OpenTelemetry JS SDK v1 and could not pick up the LangfuseSpanProcessor, which is built on the OpenTelemetry JS SDK v2 ( vercel/otel#154). With @vercel/otel v2+, registerOTel({ spanProcessors: [new LangfuseSpanProcessor()] }) exports traces as expected.
Alternatively, use the manual OpenTelemetry setup via NodeSDK and register the LangfuseSpanProcessor. See the TypeScript instrumentation docs for a full example.