langfuse-common-errors

name	langfuse-common-errors
description	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".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","langfuse","debugging"]
compatibility	Designed for Claude Code

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 =  ({ : [ ()] });
sdk.();

 sdk.(); 


 langfuse.();


process.(,  () => {
   langfuse.();
});