Skip to main content

Troubleshooting Guide

Setup Issues​

Invalid or Missing API Key​

Symptom: Traces don't appear, 401 errors

Fix:

  • Verify key starts with tk_live_
  • Check environment variable loaded correctly
  • Confirm key not revoked in dashboard
// Verify
console.log('Key:', process.env.TECKEL_API_KEY?.substring(0, 8));
// Should log: "tk_live_"

Missing Required Fields​

Symptom: Validation errors or silent failures

Fix: All traces require query and response

// WRONG
tracer.trace({ query: userQuestion })

// CORRECT
tracer.trace({ query: userQuestion, response: aiAnswer })

Enable Debug Mode​

const tracer = new TeckelTracer({
  apiKey: process.env.TECKEL_API_KEY,
  debug: true  // See all operations
});

Output includes: Initialization, trace submissions, network errors, validation warnings

Serverless Issues​

Traces Dropping​

Symptom: Traces work locally but not in production serverless

Fix: Call flush() before returning

tracer.trace({ query, response, sessionId, documents });
await tracer.flush(5000);  // REQUIRED in serverless
return { statusCode: 200, body: answer };

Cold Start Timeouts​

Symptom: First request after deployment fails, subsequent requests work

Fix: Increase timeoutMs for platform:

// AWS Lambda with containers
const tracer = new TeckelTracer({
  apiKey: process.env.TECKEL_API_KEY,
  timeoutMs: 10000  // 10 seconds
});

// Cloudflare Workers
const tracer = new TeckelTracer({
  apiKey: process.env.TECKEL_API_KEY,
  timeoutMs: 3000  // 3 seconds (fast cold starts)
});

Cold start times: Vercel (1-3s), Lambda (1-5s, up to 10s with containers), Cloud Run (2-4s), Workers (under 500ms)

Network Issues​

Connectivity Test​

# Should return 401 (proves API is reachable)
curl -X POST https://app.teckel.ai/api/sdk/traces \
  -H "Content-Type: application/json" \
  -d '{"traces": [{"query": "test", "response": "test"}]}'

Common blocks: Corporate firewalls, VPN/proxy issues, DNS failures

High Latency​

Symptom: Traces fail in production, especially distant regions

Fix: Increase timeout

const tracer = new TeckelTracer({
  apiKey: process.env.TECKEL_API_KEY,
  timeoutMs: 10000,  // For high latency regions
  debug: true        // Monitor actual latency
});

Runtime Issues​

Node.js Too Old​

Error: TypeError: fetch is not a function

Fix: Upgrade to Node.js 18+

node --version  # Should be v18.0.0+
nvm install 18 && nvm use 18

Deno Import​

// CORRECT
import { TeckelTracer } from "npm:teckel-ai@^0.7.0";

// WRONG
import { TeckelTracer } from "teckel-ai";

Bun​

bun add teckel-ai  # Don't mix with npm

Data Issues​

DateTime Validation Errors​

Symptom: "Invalid datetime in lastUpdated"

Fix: Use .toISOString()

// WRONG
lastUpdated: chunk.updated_at  // "2024-01-05 18:30:45"

// CORRECT
lastUpdated: new Date(chunk.updated_at).toISOString()  // "2024-01-05T18:30:45.123Z"

Common sources:

// PostgreSQL/MySQL
new Date(row.updated_at).toISOString()

// MongoDB
doc.updatedAt.toISOString()

// File API
new Date(file.lastModifiedDate).toISOString()

// fs.stat
stats.mtime.toISOString()

No Freshness Scores​

Cause: Missing lastUpdated

Fix: Always include timestamp in ISO 8601 format

Low Accuracy Scores​

Common causes:

  1. Document mismatch - Send exact chunk, not summary
  2. Incomplete list - Include ALL chunks sent to LLM
  3. Timing - Only trace AFTER LLM completes
// CORRECT
const answer = await llm.generate(query, chunks);
tracer.trace({ query, response: answer, documents });

Inconsistent Document References​

Symptom: Documents in traces but no dashboard scores

Fix: Use consistent id values (any format works, but keep it consistent)

// CORRECT - Consistent id
id: 'password-reset-guide-v2.md'  // Any format works
id: 'doc-123'                     // Sequential IDs fine too

// WRONG - Inconsistent casing
id: 'Password-Reset-Guide-v2.md'  // Trace 1
id: 'password-reset-guide-v2.md'  // Trace 2 (different!)

// BEST PRACTICE - Use your existing document IDs
id: chunk.documentId  // From your system

Dashboard Issues​

Topics Not Appearing​

Requirements:

  • Minimum 100 queries
  • Similar queries must exist to form groups

Timeline:

  • Traces appear: Immediately
  • Topics appear: When created or after sufficient data

Document Scores Missing​

Causes:

  • Processing delay (10-60 minutes)
  • Inconsistent document IDs
  • Not enough traces using documents

Error Responses​

Rate Limiting (429)​

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Limits: 1,000 requests/hour, resets on the hour

SDK automatically retries - no action needed

Validation Errors (400)​

// Missing field
tracer.trace({ query: 'test' });
// Error: response is required

// Field too long
query: veryLongString
// Error: query too long (max 10,000 chars)

// Invalid document
documents: [{ id: 'doc-123' }]
// Error: name required, text required

// Invalid type
latencyMs: -100
// Error: latencyMs must be positive

Testing Checklist​

Before deploying:

  1. Test with debug mode
const tracer = new TeckelTracer({
  apiKey: process.env.TECKEL_API_KEY,
  debug: true
});

  1. Verify trace in dashboard - Check Audit History within 30 seconds

  2. Test serverless

tracer.trace({ query, response, sessionId, documents });
await tracer.flush(5000);
  1. Test error handling - Invalid API key should log warning but not crash

Getting Help​

Documentation:

Contact support@teckel.ai with:

  • Organization name
  • Error messages from debug mode
  • Example trace payload
  • Environment (Node.js version, platform)
  • Time when issue occurred (with timezone)