Troubleshooting & FAQ

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

Authentication issues

• 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.

No traces appearing

• 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") to inspect exporter output.

Incorrect nesting or missing spans

• 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 spans (langfuse.start_span()), always call .end().
• In async code, rely on Langfuse helpers to avoid losing context across await boundaries.

LangChain/OpenAI integration issues

• 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.

Media not appearing

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

Missing traces with @vercel/otel

• Use the manual OpenTelemetry setup via NodeSDK and register the LangfuseSpanProcessor. The @vercel/otel helper does not yet support the OpenTelemetry JS SDK v2 that Langfuse depends on. See the TypeScript instrumentation docs for a full example.