Troubleshooting

SDK Disabled in Production

Symptom

No traces appear after deploying to production, even though traces work in local development.

Cause

The Glasstrace SDK includes a production guard that disables itself when NODE_ENV === 'production' or VERCEL_ENV === 'production'. This prevents accidental trace capture in production environments.

Fix

This is expected behavior. The SDK is designed for development and staging environments only.

If you are running a local production build (e.g., next build && next start) and want traces, set the force-enable flag:

GLASSTRACE_FORCE_ENABLE=true next start

Do not set GLASSTRACE_FORCE_ENABLE=true in actual production deployments. The production guard exists to protect your application’s performance and your trace budget.

See Configuration for all environment variables.

---

Rate Limited

Symptom

The ingestion API returns 429 Too Many Requests.

Cause

Your application is sending more traces per minute than your tier allows.

Rate limits by tier:

Tier	Traces per minute
Anonymous	100
Free Trial	500
Pro	2,000

Fix

1. Check which tier your account is on in the dashboard.
2. Reduce trace volume by adjusting capture settings or sampling.
3. Upgrade your tier if you need higher throughput.

The rate limit response uses the standard error shape and includes a Retry-After header:

{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Limit: 100 requests per minute",
  "retryable": true,
  "requestId": "<request-id>"
}

The Retry-After header (in seconds) indicates how long to wait before retrying. The response also includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

---

Anonymous Traces Disappeared

Symptom

MCP tools return no traces or empty results after using Glasstrace anonymously for more than 48 hours.

Cause

Anonymous traces have a 48-hour storage TTL. Traces older than 48 hours are automatically deleted. The anonymous key itself does not expire — only the traces stored under it.

Storage TTL by tier:

Tier	Storage TTL
Anonymous	48 hours
Free Trial	7 days
Pro	90 days

Fix

This is expected behavior for anonymous mode. To retain traces longer, sign up for an account:

• Free Trial: 7-day TTL (30-day trial, credit card required at signup)
• Pro: 90-day TTL

See Auth & Keys for details on the signup and claim flow.

---

enrichment_pending Status

Symptom

The get_root_cause MCP tool returns status: "pending" instead of enrichment results.

Cause

LLM enrichment runs asynchronously via Upstash Workflow. After a trace is captured, enrichment is queued and processed in the background. The pending status means enrichment has not completed yet.

Fix

Wait 5-30 seconds and retry the get_root_cause call.

The get_root_cause response uses these status values:

Status	Meaning
"completed"	Enrichment finished. Results available.
"pending"	Enrichment in progress or queued. Retry shortly.
"failed"	Enrichment encountered an error.
"unavailable"	Enrichment not attempted (anonymous tier or enrichment disabled).

If the status stays "pending" for more than 60 seconds:

1. Verify your account is active and not lapsed.
2. Verify enrichment is enabled for your tier (enrichmentEnabled is true for Free Trial and Pro tiers, false for Anonymous).
3. Check the MCP Server docs for additional diagnostics.

---

No Traces Found

Symptom

MCP tools return empty results even though you expect traces to be present.

Cause

This can happen for several reasons:

• The SDK is not initialized in your application.
• The GLASSTRACE_ENV variable is set to a different environment than expected.
• Traces have expired based on your tier’s storage TTL.

Fix

1. Verify registerGlasstrace() is called in your instrumentation.ts file:

instrumentation.ts

import { registerGlasstrace } from "@glasstrace/sdk";

export function register() {
  registerGlasstrace();
}

2. If you set GLASSTRACE_ENV, verify it matches the environment you are querying:

echo $GLASSTRACE_ENV

3. Check your tier’s storage TTL — traces may have expired:
   • Anonymous: 48 hours
   • Free Trial: 7 days
   • Pro: 90 days

See SDK Reference for initialization details.

---

Source Maps Unavailable

Symptom

Stack traces in MCP tool responses show minified or compiled JavaScript instead of your TypeScript source.

Cause

Anonymous mode does not upload source maps. Without an API key, the SDK skips source map upload during builds.

Fix

1. Set the GLASSTRACE_API_KEY environment variable:

export GLASSTRACE_API_KEY=<your-api-key>

2. Wrap your Next.js config with withGlasstraceConfig():

next.config.ts

import { withGlasstraceConfig } from "@glasstrace/sdk";

export default withGlasstraceConfig({
  // your Next.js config
});

3. Run next build — source maps will be uploaded automatically.

See Configuration for build integration details.

---

MCP Connection Failures

Symptom

Your AI agent cannot connect to the Glasstrace MCP server.

Cause

• Wrong endpoint URL in the MCP configuration.
• Missing or malformed Bearer token.
• Network connectivity issue.

Fix

1. Verify the endpoint is https://api.glasstrace.dev/mcp.

2. Verify the Bearer token is set. The token is either your API key (GLASSTRACE_API_KEY) or the auto-generated anonymous key from .glasstrace/anon_key.

3. Test connectivity with curl:

curl -X POST https://api.glasstrace.dev/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

A successful response returns a JSON-RPC result with the available tools list. If you get a connection error, check your network and firewall settings.

See MCP Server for full configuration instructions.

---

Auth Failures (401/403)

Symptom

The API returns 401 Unauthorized or 403 Forbidden.

Cause

Several conditions can trigger auth failures:

• 401 Unauthorized: Invalid, expired, or revoked API key.
• 403 Forbidden: Subscription expired or inactive, or wrong credential type for the endpoint (e.g., using an anonymous key on an endpoint that requires a development API key).

Fix

1. Verify the key format matches the expected prefix:

Key type	Prefix	How obtained
Anonymous	gt_anon_xxx	Auto-generated by SDK on first run
Development API key	gt_dev_xxx	Created via dashboard after signup

2. If you receive a 403, check whether your subscription is active. A lapsed subscription returns:

{
  "code": "subscription_expired",
  "message": "Subscription expired or inactive",
  "retryable": false,
  "requestId": "<request-id>"
}

3. If you receive a 401, verify the key has not been revoked and regenerate it from the dashboard if needed:

{
  "code": "invalid_key",
  "message": "Invalid or expired authentication credentials",
  "retryable": false,
  "requestId": "<request-id>"
}

See Auth & Keys for key management details.

---

Import Graph Not Captured

Symptom

The get_test_suggestions MCP tool returns an empty coverage map (Part 1 returns no data).

Cause

Import graph capture is opt-in. It is controlled by the CaptureConfig.importGraph setting, which defaults to false.

Fix

1. Enable import graph capture in the dashboard capture settings.

2. Verify your tier supports the coverage map feature:

Tier	coverageMapEnabled
Anonymous	false
Free Trial	true
Pro	true

Coverage map requires coverageMapEnabled, which is available on Free Trial and Pro tiers (not Anonymous).

After enabling, run a new build to capture the import graph. The get_test_suggestions tool will include coverage data on the next query.

---

Still Stuck?

If none of the above solutions resolve your issue, your AI agent can call get_latest_error to retrieve the most recent error trace for additional context. You can also check the SDK Reference and MCP Server docs for detailed API documentation.