Langfuse Authentication Troubleshooting Guide

Quick Debugging Steps

1. Visit the debug page: Navigate to /debug/langfuse in your app
2. Check the browser console: Look for detailed logs starting with [LangfuseTracing]
3. Test the API endpoint: Visit /api/debug/langfuse to check server-side configuration
4. Run console commands:

   debugLangfuseStatus()
   testLangfuseConnection()
   

Common Issues and Solutions

1. Public Key Not Found

Symptoms:

• Console shows: “Langfuse not initialized - no public key available”
• debugLangfuseStatus() shows hasPublicKey: false

Solutions:

For Local Development:

1. Check your .env.local file has:

   NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY=your-actual-key-here
   

2. Ensure the key starts with pk- (public key) or similar prefix
3. Restart your development server after adding/changing env vars:

   npm run dev
   

For Production Deployment: Environment variables must be added to GCP Secret Manager:

1. Download current secrets: gcloud secrets versions access latest --secret=FIREBASE_ENV --project YOUR_PROJECT_ID > .env.local
2. Add/update the variables in .env.local
3. Upload back to Secret Manager: gcloud secrets versions add FIREBASE_ENV --data-file=.env.local --project YOUR_PROJECT_ID
4. Redeploy frontend to pick up new secrets

2. Wrong Key Format

Symptoms:

• Console warning: “Public key format may be incorrect”
• Authentication failures despite key being present

Solutions:

1. Verify your Langfuse public key format:
   • Should look like: pk-lf-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   • Contains dashes/hyphens
   • Is the PUBLIC key, not the secret key
2. Check you haven’t accidentally used the secret key as the public key

3. Base URL Issues

Symptoms:

• Connection timeouts or 404 errors
• Using default URL when you have a custom instance

Solutions:

1. For Langfuse Cloud (default):

   NEXT_PUBLIC_LANGFUSE_BASE_URL=https://cloud.langfuse.com
   

2. For self-hosted:

   NEXT_PUBLIC_LANGFUSE_BASE_URL=https://your-langfuse-instance.com
   

3. Ensure the URL doesn’t have a trailing slash

4. Client vs Server Issues

Symptoms:

• Works on server but not client, or vice versa
• Different behavior in development vs production

Solutions:

Environment Variable Configuration:

Local Development (.env.local):

# Client-side variables (available in browser)
NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY=xxx
NEXT_PUBLIC_LANGFUSE_BASE_URL=xxx

# Server-side variables (API routes only)
LANGFUSE_SECRET_KEY=xxx

Production Deployment: All variables above must be added to GCP Secret Manager under FIREBASE_ENV secret. See production deployment steps in the previous troubleshooting section.

Debug Configuration: Use the debug API endpoint to check server config:

curl http://localhost:3000/api/debug/langfuse

5. Build vs Runtime Configuration

Symptoms:

• Environment variables not updating after changes
• Works locally but not in production

Solutions:

1. For local development, restart the dev server
2. For production, rebuild the application:

   npm run build
   npm start
   

3. Check if using runtime config in next.config.mjs:

   publicRuntimeConfig: {
     NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY: process.env.NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY,
     NEXT_PUBLIC_LANGFUSE_BASE_URL: process.env.NEXT_PUBLIC_LANGFUSE_BASE_URL
   }
   

Debugging Commands

Browser Console Commands

// Check current status
debugLangfuseStatus()

// Test the connection
await testLangfuseConnection()

// Manual trace test
const traceId = langfuseTracing.createTrace({ name: 'manual-test' })
langfuseTracing.addEvent('test-event', { data: 'test' })
langfuseTracing.endTrace()

API Debug Endpoint

# Check server-side configuration
curl http://localhost:3000/api/debug/langfuse

# Pretty print the JSON response
curl http://localhost:3000/api/debug/langfuse | jq

Configuration Checklist

• .env.local file exists and contains Langfuse keys
• Public key starts with correct prefix (e.g., pk-)
• Public key is in NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY (note the NEXT_PUBLIC_ prefix)
• Base URL is correctly set (default: https://cloud.langfuse.com)
• Dev server restarted after env changes
• No trailing slashes in URLs
• Keys don’t contain extra spaces or quotes
• Using the correct key (public vs secret)
• For production: Environment variables are set in hosting platform

Still Having Issues?

1. Check the Langfuse dashboard for any error messages
2. Verify your Langfuse project settings
3. Test with a minimal example:

   import { Langfuse } from 'langfuse';
      
   const langfuse = new Langfuse({
     publicKey: 'your-key-here',
     baseUrl: 'https://cloud.langfuse.com'
   });
      
   const trace = langfuse.trace({ name: 'test' });
   trace.event({ name: 'test-event' });
   

4. Check network requests in browser DevTools for failed API calls
5. Look for CORS errors or blocked requests

Contact Support

If none of the above solutions work:

1. Gather debug information using debugLangfuseStatus()
2. Check browser console for error messages
3. Test the API debug endpoint
4. Contact Langfuse support with the debug output