Skip to main content

Troubleshooting Guide

Setup Issues​

Invalid or Missing API Key​

Symptom: Traces don't appear, 401 errors

Fix: Verify your key starts with tk_live_, is loaded in the runtime environment, and has not been revoked.

Missing Required Fields​

Symptom: Validation errors or silent failures

Fix: Every trace requires both query and response.

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

Enable Debug Mode​

Enable debug logging to inspect validation and delivery behavior.

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

Delivery Issues​

Traces Dropping​

Symptom: Traces work locally but not in production serverless

Fix: Call flush() before returning from serverless handlers.

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

Timeout or Latency Failures​

Symptom: Intermittent send failures in production.

Fix: Increase SDK timeout, confirm outbound network access to https://app.teckel.ai, and keep debug mode enabled while validating.

Connectivity Checks​

API Reachability Test​

# A 401 here confirms the endpoint is reachable and auth is being enforced.
curl -X POST https://app.teckel.ai/api/sdk/traces \
  -H "Content-Type: application/json" \
  -d '{"traces": [{"query": "test", "response": "test"}]}'

Runtime Issues​

Runtime Compatibility​

Use a supported runtime (Node.js 18+ for TypeScript SDK). Ensure your package import style matches your runtime.

Data Issues​

DateTime Validation Errors​

Symptom: "Invalid datetime in lastUpdated"

Fix: Send lastUpdated as an ISO 8601 UTC string.

lastUpdated: new Date(sourceTimestamp).toISOString()

No Freshness Scores​

Cause: Missing lastUpdated

Fix: Always include lastUpdated in ISO 8601 UTC format.

Low Accuracy Scores​

Common causes:

  • Document mismatch: sent summary/rewritten content instead of exact retrieved chunks.
  • Incomplete retrieval set: omitted some chunks actually provided to the LLM.
  • Trace timing: trace emitted before generation completed.

Inconsistent Document References​

Symptom: Documents in traces but no dashboard scores

Fix: Keep documents[].id stable and case-consistent across traces.

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 Codes​

429 Rate Limited​

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

The SDK retries transient failures automatically.

400 Validation Failed​

Validate field constraints against HTTP API Reference and confirm required fields are present.

Testing Checklist​

Before deploying:

  1. Enable debug: true and verify no validation warnings.
  2. Confirm traces appear in the dashboard.
  3. In serverless, verify flush() runs before return.
  4. Verify invalid key handling logs errors without crashing your app.
const tracer = new TeckelTracer({
  apiKey: process.env.TECKEL_API_KEY,
  debug: true
});

Need Help​

Contact support@teckel.ai with:

  • Organization name
  • Error message(s)
  • Example payload
  • Runtime/platform details
  • Timestamp (include timezone)