Troubleshooting & FAQ
If you cannot find your issue below, try Ask AI, open a GitHub issue, or contact support.
Seeing AttributeError or is not a function errors after upgrading? Follow the Python v4 → v5 and JS/TS v5 → v6 migration guides.
- Ensure
LANGFUSE_PUBLIC_KEY,LANGFUSE_SECRET_KEY, andLANGFUSE_BASE_URLare set as environment variables or passed toLangfuse()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_enabledisTrueandsample_rateis not0.0. - Call
langfuse.shutdown()(orlangfuse.flush()in short-lived jobs) so queued data is exported. - Enable debug logging (
debug=TrueorLANGFUSE_DEBUG="True"on Python,LANGFUSE_DEBUG="true"orLANGFUSE_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
awaitboundaries. - 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 openaiorLangfuseCallbackHandler) are instantiated before API calls. - Check version compatibility between Langfuse, LangChain, and the model SDKs.
- Use
LangfuseMediaobjects for audio/image payloads and inspect debug logs to surface upload errors (uploads run on background threads).
- Make sure you are on
@vercel/otelv2 or later. Versions before v2 were built on the OpenTelemetry JS SDK v1 and could not pick up theLangfuseSpanProcessor, which is built on the OpenTelemetry JS SDK v2 (vercel/otel#154). With@vercel/otelv2+,registerOTel({ spanProcessors: [new LangfuseSpanProcessor()] })exports traces as expected. - Alternatively, use the manual OpenTelemetry setup via
NodeSDKand register theLangfuseSpanProcessor. See the TypeScript instrumentation docs for a full example.