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".
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):
Data not flushed before process exits
Wrong project keys (traces going to different project)
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.
// 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