Reference

Troubleshooting

Debug SDK issues using the diagnostic system, status API, and common solutions.

SDK Status

Check the SDK's current state:

Example

const gt = useGoaTech();
const status = gt.status();

console.log({
  initialized: status.initialized,
  online: status.online,
  queueDepth: status.queueDepth,
  offlineQueueDepth: status.offlineQueueDepth,
  lastFlushAt: status.lastFlushAt,
  userId: status.userId,
  deviceId: status.deviceId,
  flagCount: status.flagCount,
  experimentCount: status.experimentCount,
  sdkVersion: status.sdkVersion,
});

Diagnostic Events

The SDK emits structured diagnostic events for debugging. Enable via the onDiagnostic callback:

goatech.ts

const gt = GoaTech.create({
  apiKey: "lp_pub_...",
  onDiagnostic: (event) => {
    if (event.severity === "error") {
      console.error(`[GoaTech] ${event.code}: ${event.message}`, event.data);
    }
  },
});

Or subscribe after initialization:

Example

const bus = gt.diagnostics();
const unsubscribe = bus.subscribe(
  (event) => console.log(event),
  { minSeverity: "warn" } // Only warn and error
);

// Later: unsubscribe();

Diagnostic Event Structure

Each diagnostic event contains:

Field	Type	Description
`timestamp`	`string`	ISO 8601 timestamp
`severity`	`"debug" \| "info" \| "warn" \| "error"`	Severity level
`category`	`string`	Category (transport, config, identity, lifecycle, flag, experiment, connectivity)
`code`	`string`	Machine-readable code (e.g., `transport.flush_failed`)
`message`	`string`	Human-readable description
`data`	`object?`	Structured payload with details
`requestId`	`string?`	Correlates with API `X-Request-ID` header

Recent Diagnostics

Access the ring buffer of recent diagnostic events:

Example

const events = gt.getRecentDiagnostics();
// Returns the last N events (default buffer size: 100)

// Filter by category
const transportErrors = events.filter(
  e => e.category === "transport" && e.severity === "error"
);

Common Issues

Flags returning default values

Check that your API key is correct and matches the environment
Verify flag config has loaded: gt.status().flagCount > 0
Ensure the flag key matches exactly (case-sensitive)
Check targeting rules — your user traits may not match

Events not appearing in dashboard

Events are batched — wait for the flush interval (default 5s) or call flush()
Check status().queueDepth — if events are queuing, there may be a connectivity issue
Check status().online — the SDK may be in offline mode
Verify your API key has write permissions

Experiment returning "control" unexpectedly

The experiment may not be in "running" status
The user may not be in the traffic allocation percentage
Check status().experimentCount > 0 to verify config loaded
Call getRecentDiagnostics() and filter for category: "experiment"

SDK not initializing

Check browser console for errors
Verify NEXT_PUBLIC_GT_KEY is set in your environment
Enable debug mode: debug: true in config
Check that the API URL is reachable

Server SDK: "GT_SECRET_KEY is not set"

The getGoaTech() helper requires GT_SECRET_KEY in your environment
Ensure the env var is available at runtime (not just build time)
For local development, add it to your .env.local file

Debug Mode

Enable verbose logging with the debug flag:

goatech.ts

GoaTech.create({
  apiKey: "lp_pub_...",
  debug: true, // Logs all operations to console
});