Diagnose and fix common Langfuse errors and exceptions. Use when encountering Langfuse errors, debugging missing traces, or troubleshooting integration issues. Trigger with phrases like "langfuse error", "fix langfuse", "langfuse not working", "debug langfuse", "traces not appearing".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill langfuse-common-errorsLoading…
Diagnostic reference for the 10 most common Langfuse integration errors, with real error messages, root causes, and tested solutions.
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"
Symptom: Code runs without errors but no traces show in UI.
Root causes (in order of likelihood):
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();
});
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 });
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 },
});
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();
});
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" });
});
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
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");
}
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
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
#!/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)"
langfuse-debug-bundle skill
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).