Operations Guides
Troubleshooting

Troubleshooting

This guide covers the current Grounded SDK and the current /api integration model.

Packages Are Not On npm Yet

Symptom

npm install @grounded/client, @grounded/tracing, or @grounded/analytics fails or returns 404.

Meaning

The implementation exists in the Grounded monorepo, but the public npm publish may not be live yet for your environment.

Fix

Use the monorepo workspace packages for now.

401 Unauthorized

Common Causes

  • missing Authorization header
  • invalid key
  • expired key
  • revoked key

Fix

  • verify the key prefix matches the package
  • verify the exact secret value, not just the prefix
  • rotate the key if needed

403 Forbidden

Common Causes

  • wrong key kind for the route
  • missing scope
  • agent-scoped key trying to access another agent

Examples

  • publishable key calling /api/jobs
  • key missing connectors:write
  • publishable key writing telemetry for another agent

Tracing Throws Before Send

Common Causes

  • no agent could be resolved
  • no stitch key was provided

Fix

Make sure each trace has:

  • an agentId
  • and one of:
    • sessionId
    • anonymousId
    • userId plus non-empty correlationKeys

Traces Are Accepted But Not Showing Up As Sessions

Common Causes

  • no snapshot exists for that agent
  • resource.snapshotId belongs to another agent
  • correlation keys do not line up with browser telemetry or existing trace data

What To Check

  • grounded.traces.get(traceId) works
  • the agent has at least one snapshot
  • the trace and telemetry use the same sessionId / anonymousId handoff

If Grounded cannot resolve a snapshot, the trace is stored but not normalized into a session.

Browser Telemetry And Backend Traces Are Not Merging

Common Causes

  • you did not forward analytics.getContext() to the backend
  • the backend generated a different sessionId
  • the browser and backend point at different agents

Fix

  • call const ctx = analytics.getContext()
  • send that context to the backend
  • reuse ctx.sessionId, ctx.anonymousId, and ctx.userId in tracing.startTrace(...)

Trace Batch Returns 207 Multi-Status

Meaning

Some traces in the batch were accepted and some were rejected.

What To Do

Inspect the returned per-trace results. Common rejection reasons:

  • invalid timestamps
  • missing agent
  • invalid snapshot
  • wrong agent scope on the API key

OpenAI Wrapper Did Nothing

Common Causes

  • there was no active trace context
  • you called OpenAI outside trace.run()

Fix

Prefer:

await trace.run(async () => {
  await openai.responses.create(...);
});

jobs.wait() Throws

Meaning

The job reached a terminal state of:

  • failed
  • cancelled

Fix

Catch GroundedJobError and inspect error.job.

Connector Sync Is Queued But Nothing Happens

Common Causes

  • worker or queue backend is down
  • connector config is incomplete
  • sync job was created but not executed

What To Check

  • grounded.connectors.sync() returned a job ID
  • the job exists in /api/jobs/:jobId
  • the worker is running

Base URL Problems

These are both valid:

  • http://localhost:3001
  • http://localhost:3001/api

If requests still fail, check that you are pointing at the Grounded API server and not another origin.

Best Practices