Guides
Troubleshooting

Troubleshooting

Common issues and solutions when using the Grounded Intelligence SDK.

SDK Not Sending Events

Problem

Events are not appearing in the dashboard.

Solutions

1. Check initialization:

console.log('Lumina initialized:', Lumina.getDistinctId())

2. Verify endpoint:

curl -X POST http://your-endpoint/collect/sdk/events \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/x-ndjson" \
  -d '{"source":"test","name":"ping"}'

3. Ensure finish() is called:

// Always use try/finally
const turn = session.turn()
try {
  await turn.wrapLLM(/* ... */)
} finally {
  await turn.finish()  // Must be called
}

4. Check write key:

Lumina.init({
  writeKey: 'gi_xxxxx',  // Must start with 'gi_'
  endpoint: 'https://your-ingest-server.com',
})

Events Not Appearing in Dashboard

Problem

SDK is sending events but they don't appear in the dashboard.

Common Causes

  1. Wrong API key - Verify write key in dashboard
  2. Wrong project ID - Ensure correct project selected
  3. Events not flushed yet - Wait 5s or force flush manually
  4. Workers not running - Check ingest server status

Manual Flush

// Force immediate flush
await Lumina.flush()

TypeScript Errors

Problem

Type errors when using the SDK.

Solutions

1. Ensure correct imports:

import { Lumina, CaptureTranscript } from 'lumina-sdk'
import type {
  LuminaConfig,
  SessionCtx,
  TurnCtx,
} from 'lumina-sdk'

2. Check peer dependencies:

npm install posthog-js  # If using PostHog provider

3. Verify tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Provider Errors

Problem

Provider initialization failures (e.g., PostHog).

Solutions

1. Install peer dependencies:

npm install posthog-js

2. Initialize provider before SDK:

// Initialize PostHog first
posthog.init('phc_xxxxx', {
  api_host: 'https://us.posthog.com'
})
 
// Then initialize Lumina
Lumina.init({
  uiAnalytics: postHogProvider({
    apiKey: 'phc_xxxxx',
    host: 'https://us.posthog.com'
  })
})

3. Use dummy provider if not using UI analytics:

function createDummyProvider() {
  return {
    name: 'none',
    init: () => {},
    getSessionId: () => '',
    getReplayUrl: () => '',
    tagTurn: () => {},
    untagTurn: () => {},
    startReplay: () => {},
    stopReplay: () => {},
    captureEvent: () => {},
    shutdown: () => {},
  }
}
 
Lumina.init({
  uiAnalytics: createDummyProvider(),
})

SDK Not Initializing

Problem

SDK methods throw "not initialized" errors.

Solution

Ensure init() is called before any event capture:

// ✅ Correct order
Lumina.init({ /* ... */ })
const session = await Lumina.session.start()
 
// ❌ Wrong order
const session = await Lumina.session.start()
Lumina.init({ /* ... */ })  // Too late!

Events Lost on Page Reload

Problem

Events are lost when the user refreshes the page.

Explanation

This is expected behavior. The SDK buffers events in memory and flushes on:

  1. Timer (flushIntervalMs)
  2. Size (maxBatchBytes)
  3. Visibility change (tab hide)

Solutions

1. Reduce flush interval:

Lumina.init({
  flushIntervalMs: 1000,  // Flush every 1s (default: 5s)
})

2. Call finish() synchronously:

await turn.finish()  // Wait for flush before allowing navigation

High Memory Usage

Problem

SDK consuming too much memory.

Solutions

1. Reduce batch size:

Lumina.init({
  maxBatchBytes: 50_000,  // 50KB (default: 100KB)
})

2. Don't capture large transcripts:

Lumina.init({
  captureTranscript: CaptureTranscript.None,  // Don't capture transcripts
})

3. Sample events:

Lumina.init({
  sampling: {
    turn: 0.1,  // Only capture 10% of turns
  }
})

Network Errors

Problem

Network requests to ingest server failing.

Solutions

1. Check endpoint URL:

Lumina.init({
  endpoint: 'https://your-ingest-server.com',  // Must be valid URL
})

2. Verify CORS headers: If calling from browser, ensure ingest server has CORS enabled:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Api-Key

3. Check network connectivity:

curl -X POST https://your-ingest-server.com/collect/sdk/events \
  -H "X-Api-Key: gi_xxxxx" \
  -H "Content-Type: application/x-ndjson" \
  -d '{"source":"test"}'

Identity Not Persisting

Problem

User identity resets on page reload.

Solutions

1. Check cookies are enabled: The SDK stores identity in cookies (lumina_id). Ensure cookies are not blocked.

2. Verify cookie domain:

// Check if cookie is set
document.cookie.split(';').find(c => c.includes('lumina_id'))

3. Check localStorage:

// Backup in localStorage
localStorage.getItem('lumina_id')

Getting Help

If you're still stuck:

  1. Check the docs: Review SDK Reference and Best Practices
  2. GitHub Issues: github.com/groundedintelligence/sdk/issues (opens in a new tab)
  3. Email: support@groundedintelligence.ai

When reporting issues, include:

  • SDK version (npm list lumina-sdk)
  • Error messages
  • Code snippet
  • Browser/Node.js version
Best Practices