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:** ```bash 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:** ```typescript // v4+: Ensure OTel SDK is shut down properly const sdk = new NodeSDK({ spanProcessors: [new LangfuseSpanProcessor()] }); sdk.start(); // ... your code ... await sdk.shutdown(); // MUS...