Agent Skills: Langfuse Common Errors

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

Resources

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