langfuse-common-errors

Overview

Diagnostic reference for the 10 most common Langfuse integration errors, with real error messages, root causes, and tested solutions.

Prerequisites

• Langfuse SDK installed
• API credentials configured
• Access to application logs or console output

Error Reference

1. Authentication Failed (401)

Error:

Langfuse: Unauthorized - Invalid API key
Error: 401 Unauthorized

Cause: API key missing, expired, revoked, or keys from wrong project.

Fix:

set -euo pipefail
# Verify env vars are set
echo "Public: ${LANGFUSE_PUBLIC_KEY:0:15}..."
echo "Secret: ${LANGFUSE_SECRET_KEY:0:10}..."

# Test auth against API
HOST="${LANGFUSE_BASE_URL:-https://cloud.langfuse.com}"
curl -s -o /dev/null -w "HTTP %{http_code}" \
  "$HOST/api/public/health"

# Auth test
curl -s -o /dev/null -w "HTTP %{http_code}" \
  -H "Authorization: Basic $(echo -n "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" | base64)" \
  "$HOST/api/public/traces?limit=1"

2. Traces Not Appearing in Dashboard

Symptom: Code runs without errors but no traces show in UI.

Root causes (in order of likelihood):

1. Data not flushed before process exits
2. Wrong project keys (traces going to different project)
3. Dashboard filter hiding traces

Fix:

// v4+: Ensure OTel SDK is shut down properly
const sdk = new NodeSDK({ spanProcessors: [new LangfuseSpanProcessor()] });
sdk.start();
// ... your code ...
await sdk.shutdown(); // MUST call this before process exits

// v3: Always flush
await langfuse.flushAsync();

// v3: Register shutdown handler for long-running processes
process.on("beforeExit", async () => {
  await langfuse.shutdownAsync();
});

3. Network / Connection Errors

Error:

FetchError: request to https://cloud.langfuse.com failed
ECONNREFUSED / ETIMEDOUT

Fix:

set -euo pipefail
# Test connectivity
curl -v https://cloud.langfuse.com/api/public/health

# Check DNS
nslookup cloud.langfuse.com

# For self-hosted
curl -v $LANGFUSE_BASE_URL/api/public/health

// Increase timeout for slow networks
// v4+: Configure via OTel span processor options
// v3:
const langfuse = new Langfuse({ requestTimeout: 30000 });

4. Missing Token Usage

Symptom: Generations appear but token counts show zero.

Fix:

// For OpenAI streaming -- enable usage reporting
const stream = await openai.chat.completions.create({
  model: "gpt-4o",
  messages,
  stream: true,
  stream_options: { include_usage: true }, // Required!
});

// For manual tracing -- always include usage on generation end
generation.end({
  output: content,
  usage: {
    promptTokens: response.usage?.prompt_tokens ?? 0,
    completionTokens: response.usage?.completion_tokens ?? 0,
  },
});

// v4+: updateActiveObservation with usage
updateActiveObservation({
  output: content,
  usage: { promptTokens: 100, completionTokens: 50 },
});

5. Spans Stuck "In Progress" (v3)

Symptom: Spans show as in-progress indefinitely in the dashboard.

Fix:

// Always end spans in try/finally
const span = trace.span({ name: "operation" });
try {
  const result = await doWork();
  span.end({ output: result });
  return result;
} catch (error) {
  span.end({ level: "ERROR", statusMessage: String(error) });
  throw error;
}

// v4+ avoids this entirely -- startActiveObservation auto-ends
await startActiveObservation("operation", async () => {
  // Span automatically ends when callback completes or throws
  return await doWork();
});

6. Duplicate Traces

Symptom: Same operation creates multiple traces.

Fix:

// Use singleton pattern -- NEVER create Langfuse per request
// BAD:
app.get("/api", async (req, res) => {
  const langfuse = new Langfuse(); // Creates new client per request
});

// GOOD:
const langfuse = new Langfuse(); // Single instance
app.get("/api", async (req, res) => {
  const trace = langfuse.trace({ name: "api-request" });
});

7. SDK Import Errors

Error:

TypeError: langfuse.trace is not a function
Cannot find module '@langfuse/tracing'

Fix:

set -euo pipefail
# Check installed version
npm list langfuse @langfuse/client @langfuse/tracing

# v3 import
# import { Langfuse } from "langfuse";

# v4+ imports
# import { LangfuseClient } from "@langfuse/client";
# import { startActiveObservation, observe } from "@langfuse/tracing";

# Update to latest
npm install @langfuse/client@latest @langfuse/tracing@latest @langfuse/otel@latest

8. Environment Variable Not Loaded

Error:

Langfuse: Missing required configuration - publicKey

Fix:

// Load .env at the very top of your entry file
import "dotenv/config";

// Or use specific path
import { config } from "dotenv";
config({ path: ".env.local" });

// Validate on startup
if (!process.env.LANGFUSE_PUBLIC_KEY) {
  throw new Error("LANGFUSE_PUBLIC_KEY not set");
}

9. Self-Hosted Connection Issues

Error:

Failed to connect to localhost:3000
Certificate verification failed

Fix:

set -euo pipefail
# Check if Langfuse container is running
docker ps | grep langfuse

# Health check
curl http://localhost:3000/api/public/health

# Common issue: trailing slash in URL
# BAD:  LANGFUSE_BASE_URL=http://localhost:3000/
# GOOD: LANGFUSE_BASE_URL=http://localhost:3000

10. Rate Limiting (429)

Error:

Error: 429 Too Many Requests
Retry-After: 60

Fix:

// v3: Increase batch size to reduce API calls
const langfuse = new Langfuse({
  flushAt: 50,         // Batch more events
  flushInterval: 30000, // Flush less often (30s)
});

// For sustained high volume, see langfuse-rate-limits skill

Quick Diagnostic Script

#!/bin/bash
set -euo pipefail

echo "=== Langfuse Diagnostics ==="
echo "Node: $(node --version 2>/dev/null || echo 'N/A')"
echo "Python: $(python3 --version 2>/dev/null || echo 'N/A')"
echo ""

# SDK versions
echo "--- Installed SDK ---"
npm list langfuse @langfuse/client @langfuse/tracing 2>/dev/null || echo "npm: not found"
pip show langfuse 2>/dev/null | grep Version || echo "pip: not found"
echo ""

# Config check
echo "--- Config ---"
echo "Public Key: ${LANGFUSE_PUBLIC_KEY:+SET (${LANGFUSE_PUBLIC_KEY:0:10}...)}"
echo "Secret Key: ${LANGFUSE_SECRET_KEY:+SET}"
echo "Base URL: ${LANGFUSE_BASE_URL:-${LANGFUSE_HOST:-default cloud}}"
echo ""

# Connectivity
HOST="${LANGFUSE_BASE_URL:-${LANGFUSE_HOST:-https://cloud.langfuse.com}}"
echo "--- Connectivity ---"
echo "Health: $(curl -s -o /dev/null -w '%{http_code}' $HOST/api/public/health)"

Escalation Path

1. Run diagnostic script above
2. Collect debug bundle with langfuse-debug-bundle skill
3. Check Langfuse Status
4. Search GitHub Issues
5. Ask in Discord

Instructions

1. Copy the exact error, SDK version, and Langfuse base URL from the failing environment.
2. Match it to the error reference above and apply the smallest listed fix.
3. Run the diagnostic script without printing secret values.
4. Confirm one trace or score appears in the intended project before retrying production traffic.
5. If the issue persists, collect the debug bundle and follow the escalation path.

Output

Report the matched failure class, the configuration or code change made, the diagnostic result, and whether a new trace reaches the expected Langfuse project. Do not include API keys, authorization headers, or raw customer prompts in the report.

Error Handling

If a proposed fix changes credentials, endpoint, SDK major version, or retention settings, stop after the diagnostic result and require the operator to make or approve that configuration change. Keep the original error and sanitized diagnostic output for escalation rather than retrying requests indefinitely.

Examples

For a 401 error, verify that both project keys are set and that the base URL points to the same project; then send one low-risk trace and confirm it appears in that project. For missing traces, add the documented shutdown/flush behavior, rerun the smallest reproduction, and check the dashboard before changing sampling or credentials.

Resources

• Langfuse Troubleshooting
• GitHub Issues
• Langfuse Discord
• Status Page