Troubleshooting

API error responses

When the API rejects a request, the response body includes error, message, and hint fields to help you self-diagnose without opening browser DevTools.

`error` code	Status	Meaning	Fix
`invalid_api_key`	401	API key was missing, malformed, or revoked	Ensure your key starts with `evk_` and matches an active key in Project Settings → API Keys
`invalid_payload`	400	Request body failed schema validation	Check the `issues` array for field-level errors; see the SDK reference for the expected schema
`event_too_large`	413	A single event exceeds the 64 KB limit	Trim large property values or split into multiple events
`payload_too_large`	413	The full request body exceeds the endpoint limit	For `/v1/batch` the limit is 1 MB — trim events or send smaller batches
`rate_limited`	429	Too many requests in a short window	Respect the `Retry-After` response header before retrying
`queue_unavailable`	503	Telemetry queue is temporarily down	Retry after the interval in `Retry-After`; the SDK handles this automatically
`internal_error`	500	Unexpected server error	Retry once; if it persists, open a support ticket

Events are not appearing in the dashboard

This is the most common issue. Work through these in order:

1. Check that init() was called before any capture calls.

captureEvent and captureError are no-ops if called before init().

import { init, captureEvent } from "@emit-vision/sdk-js";
 
init({ apiKey: process.env.EMIT_VISION_API_KEY }); // must come first
captureEvent("app_started");

2. Verify the API key.

The apiKey must be an evk_ prefixed string. A common mistake is passing a full URL or the wrong env var.

// Correct
init({ apiKey: "evk_live_abc123" });
 
// Wrong — this is a DSN URL, not an api key
init({ apiKey: "https://[email protected]/v1" });

3. Check the browser console for errors.

Open DevTools → Console and look for messages from @emit-vision/sdk-js. Initialization and fetch errors are logged at the warn level.

4. For Node.js: call flush() before process exit.

The Node SDK buffers events and sends them in batches. If your process exits before the buffer is flushed, events are lost.

import { flush } from "@emit-vision/sdk-node";
 
process.on("SIGTERM", async () => {
  await flush({ timeout: 5000 });
  process.exit(0);
});

installProcessHandlers() sets up SIGTERM/SIGINT handlers automatically. Call it once after init() to avoid writing the shutdown handler yourself.

SDK throws "apiKey is required" on initialization

The API key environment variable is undefined. Check:

The variable is defined in your .env file and loaded before init() is called.
Next.js: browser-side code requires the NEXT_PUBLIC_ prefix. Server-side code can use unprefixed vars.

// Browser / Next.js client component:
init({ apiKey: process.env.NEXT_PUBLIC_EMIT_VISION_API_KEY });
 
// Next.js server component or API route:
init({ apiKey: process.env.EMIT_VISION_API_KEY });

API requests return 401 Unauthorized

A 401 means the API key was rejected. Verify the key matches an active ingest token in your Emit Vision project settings.

Open Project Settings → API Keys and confirm the key prefix matches your apiKey value.
If you recently rotated the token, update EMIT_VISION_API_KEY with the new key. Rotated keys are immediately disabled.
Check that the EMIT_VISION_API_KEY environment variable is set in your deployment environment, not just locally.

CORS errors in the browser console

Access to fetch at 'https://...' from origin 'https://yourapp.com' has been blocked by CORS policy

Your app's origin may not be listed in Emit Vision's allowed origins. Add the origin in Project Settings → Allowed Origins.

For local development, http://localhost and http://localhost:<port> are allowed by default.

React: errors are not being captured

React render errors don't propagate to window.onerror — they are swallowed by React's error handling. You must add an error boundary that calls captureError() in componentDidCatch.

See the Errors page for a ready-made error boundary component.

If you are using @emit-vision/sdk-react, the <EmitVisionProvider> does not include a built-in error boundary — you need to wrap your app with one separately.

`evaluateFlags()` always returns `false` / no flags

Confirm that identify() was called with the user ID before evaluating flags. Flag targeting rules often require a user ID.
Check that the feature flags are enabled in your Emit Vision project dashboard.
Flag evaluations are cached for 30 seconds after the first init() call. If you added a new flag, wait for the cache to expire or call init() again with forceRefresh: true.

Sessions are not being tracked

Session tracking requires sessionId to be set, either manually or via the autoSession option (if available). By default, the SDK does not create sessions automatically.

import { init } from "@emit-vision/sdk-js";
 
const sessionId =
  sessionStorage.getItem("emit_session_id") ?? crypto.randomUUID();
sessionStorage.setItem("emit_session_id", sessionId);
 
init({
  apiKey: process.env.NEXT_PUBLIC_EMIT_VISION_API_KEY,
  sessionId,
});

See the Sessions page for the full pattern including session rotation.

TypeScript: "Module not found" for SDK packages

Make sure the package is installed and the import path is correct:

npm install @emit-vision/sdk-js   # browser
npm install @emit-vision/sdk-node # Node.js
npm install @emit-vision/sdk-react # React
npm install @emit-vision/sdk-next # Next.js

If you are in a monorepo, confirm the package is listed in your package.json workspace dependencies and that you ran pnpm install (or equivalent) after adding it.

Still stuck?

Open an issue at github.com/emit-vision/sdk with:

The SDK package and version (npm list @emit-vision/sdk-js)
The browser console output or Node.js stderr
A minimal reproduction if possible