Troubleshooting

This guide helps you diagnose and resolve common issues when integrating and operating LensAI. Use the sections below to quickly find solutions to the most frequent problems.

Integration Issues

Events Not Appearing in Dashboard

Symptom: You've integrated LensAI but don't see events in your dashboard.

Common causes:

1. Incorrect API key or Project ID

Verify your credentials are correct:

console.log('API Key:', process.env.LENSAI_API_KEY?.substring(0, 10) + '...');
console.log('Project ID:', process.env.LENSAI_PROJECT_ID);

Check that:

• API key starts with lensai_ (not your provider key)
• Project ID matches the project in your dashboard
• Environment variables are loaded correctly (not undefined)

2. Network connectivity

Test connectivity to LensAI proxy:

curl -I https://api.getlens.ai/v1/health

Should return 200 OK. If not, check firewall rules or network policies blocking outbound HTTPS.

3. Provider API key not configured

LensAI needs your provider keys to forward requests. Verify in dashboard:

• Navigate to Settings → API Keys
• Confirm your provider (OpenAI, Anthropic, etc.) is listed
• Check that the key is valid (not expired or revoked)

4. Request errors

Enable debug logging to see if requests are failing:

// Node.js/TypeScript
const client = new LensAI({
  apiKey: process.env.LENSAI_API_KEY,
  projectId: process.env.LENSAI_PROJECT_ID,
  debug: true // Enable verbose logging
});

# Python
client = LensAI(
    api_key=os.getenv('LENSAI_API_KEY'),
    project_id=os.getenv('LENSAI_PROJECT_ID'),
    debug=True  # Enable verbose logging
)

Check logs for error messages indicating auth failures, timeouts, or invalid requests.

Requests Timing Out

Symptom: LLM requests take much longer than expected or timeout completely.

Common causes:

1. Network latency

LensAI adds minimal latency (typically <50ms) but network issues can compound:

• Test latency directly:

time curl -X POST https://api.getlens.ai/v1/proxy/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hi"}]}'

• If latency is high (>500ms), check your network path or consider a different provider region

2. Provider-side delays

LensAI proxies to your provider. If the provider is slow, LensAI will be slow:

• Test provider directly (bypassing LensAI) to isolate the issue
• Check provider status pages for known incidents
• Consider switching to a faster model or provider

3. Large payloads

Very long prompts or responses take time to transmit:

• Monitor token counts in dashboard
• If consistently hitting context limits, consider chunking or summarization

4. Timeout configuration

Default HTTP client timeouts may be too short:

const client = new LensAI({
  apiKey: process.env.LENSAI_API_KEY,
  projectId: process.env.LENSAI_PROJECT_ID,
  timeout: 60000 // 60 seconds (default is often 30s)
});

Authentication Errors

Symptom: Requests fail with 401 Unauthorized or 403 Forbidden.

Solutions:

401 Unauthorized:

• LensAI API key is invalid, expired, or missing
• Check that you're passing Authorization: Bearer <LENSAI_KEY> header
• Regenerate API key in dashboard if needed

403 Forbidden:

• API key is valid but lacks permissions for this project
• Verify the project ID matches the project the key was generated for
• Check that your plan allows the operation (some features require paid plans)

Provider Errors

Symptom: Requests fail with errors from OpenAI, Anthropic, or other providers.

Common issues:

Invalid provider API key:

Error: 401 Unauthorized from OpenAI

• Provider key configured in LensAI is incorrect or expired
• Update key in Settings → API Keys

Quota exceeded:

Error: 429 Rate limit exceeded

• You've hit provider's rate limit or spending cap
• Check provider dashboard for limits and adjust
• LensAI respects provider rate limits but cannot bypass them

Model not available:

Error: Model 'gpt-4' not found or not available

• Provider key doesn't have access to requested model
• Check your provider account tier and model access
• Use a different model (e.g., gpt-3.5-turbo)

Data and Metrics Issues

Costs Not Calculating Correctly

Symptom: Reported costs don't match expected values or provider bills.

Troubleshooting:

1. Pricing table outdated

LensAI uses current pricing for each model. If a provider recently changed prices:

• Wait 24 hours for pricing table to update
• Check Settings → Pricing to see current rates
• Report discrepancies to [email protected]

2. Custom pricing or discounts

If you have negotiated rates with providers, LensAI won't know unless configured:

• Contact support to configure custom pricing for your account

3. Non-LLM costs not tracked

LensAI automatically tracks LLM costs but not:

• Tool API calls (e.g., web search, database queries)
• Compute costs (e.g., EC2 instances)
• Infrastructure (e.g., CDN, storage)

Record these manually:

await client.costs.record({
  session_id: 'session_123',
  amount: 0.05,
  description: 'External API call',
  cost_type: 'api'
});

4. Currency conversion

If provider bills in non-USD currency, rates may fluctuate:

• LensAI uses USD for all reporting
• Exchange rate differences can cause small discrepancies

Missing Metadata or Attribution

Symptom: Events appear but don't have customer_id, agent, or other metadata.

Cause: Metadata not included in requests.

Solution: Always pass metadata when making calls:

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [...],
  metadata: {
    customer_id: 'user_123',
    agent: 'customer_support',
    session_id: 'session_xyz'
  }
});

Verify metadata is being captured:

• Check individual events in dashboard
• Filter by metadata fields to confirm they're indexed

Dashboards Show Zero or Unexpected Values

Symptom: Dashboard metrics are zero, null, or wildly incorrect.

Troubleshooting:

1. Date range filter

Check the selected date range:

• If set to "Today" and you haven't sent events today, metrics will be zero
• Expand to "Last 7 days" or "Last 30 days"

2. Segment filters

Active filters may exclude all data:

• Clear all filters and check if data appears
• Review filter logic (e.g., filtering for customer_id that doesn't exist)

3. Data lag

Events are processed in near-real-time but may take 30-60 seconds to appear in dashboards:

• Refresh the page
• Wait a minute and check again

4. Project selection

Ensure you're viewing the correct project:

• Check project selector in top navigation
• Events are scoped to projects; switching projects changes visible data

Performance and Reliability

Slow Dashboard Loading

Symptom: Dashboard takes a long time to load or times out.

Causes:

1. Large date range with high volume

Querying millions of events over a long period is slow:

• Reduce date range (e.g., last 7 days instead of last 90 days)
• Use pre-aggregated metrics instead of raw event queries

2. Complex filters or segments

Multi-dimensional segmentation requires more compute:

• Simplify filters (fewer dimensions)
• Use saved views for common complex queries

3. Browser performance

Large datasets can overwhelm browser rendering:

• Clear browser cache
• Use a modern browser (latest Chrome, Firefox, Safari)
• Close other tabs to free memory

Rate Limiting

Symptom: Requests are throttled or blocked.

LensAI rate limits:

• Free tier: 100 requests/minute
• Starter: 1,000 requests/minute
• Pro: 10,000 requests/minute
• Enterprise: Custom limits

Solutions:

1. Upgrade plan

If you consistently hit limits, upgrade to a higher tier.

2. Batch requests

Instead of making many small requests, batch when possible:

// Instead of:
for (const msg of messages) {
  await client.chat.completions.create({...});
}

// Do:
await Promise.all(messages.map(msg =>
  client.chat.completions.create({...})
));
// (Note: Still subject to rate limits, but more efficient)

3. Implement retries with backoff

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
      } else {
        throw error;
      }
    }
  }
}

await callWithRetry(() => client.chat.completions.create({...}));

Best Practices for Avoiding Issues

1. Test in development first

Before deploying to production:

• Verify events appear in dashboard
• Check metadata attribution is working
• Confirm costs are calculated as expected

2. Monitor error rates

Set up alerts for:

• Increased 4xx or 5xx error rates
• Unexpected cost spikes
• Missing expected events

3. Version your metadata schema

As you evolve your metadata structure, version it:

metadata: {
  schema_version: '2',
  customer_id: 'user_123',
  // ... other fields
}

This allows backward-compatible changes and easier debugging.

4. Log LensAI-specific info

In your application logs, include:

• LensAI request ID (from response headers)
• Session ID
• Customer ID
• Timestamp

This makes it easier to correlate application behavior with LensAI events.

5. Keep provider keys secure

• Never commit keys to version control
• Use environment variables or secret management systems
• Rotate keys periodically
• Monitor for unauthorized usage

6. Stay updated

• Subscribe to LensAI status updates (status.getlens.ai)
• Review changelog for new features and breaking changes
• Update SDK versions regularly for bug fixes and improvements

Getting Help

If you can't resolve an issue using this guide:

1. Check the status page

Visit status.getlens.ai to see if there's a known incident.

2. Search documentation

Use the search bar (top right) to find relevant docs.

3. Review SDK examples

Check GitHub repository for example code and integration patterns.

4. Contact support

Email [email protected] with:

• Detailed description of the issue
• Steps to reproduce
• Relevant logs or error messages
• Your project ID and time frame
• SDK version and language

5. Community forum

Join discussions at community.getlens.ai to ask questions and share solutions with other users.

Debugging Checklist

When encountering an issue, work through this checklist:

• Check LensAI status page for known incidents
• Verify API key and project ID are correct
• Confirm provider keys are configured and valid
• Enable debug logging to see detailed request/response info
• Test provider directly (bypass LensAI) to isolate the issue
• Check network connectivity and firewall rules
• Review browser console for client-side errors (dashboard issues)
• Try with a minimal test case to rule out application-specific bugs
• Check for recent changes to your code or configuration
• Review recent LensAI updates or migrations (check changelog)

Following this systematic approach will help you quickly identify and resolve most issues.