Troubleshooting

This page maps every SDK-emitted error code to its likely cause and what to try, plus a curated list of install-time issues that the error catalog alone won’t surface.

If you can run claude /vektis-troubleshoot from your project, the skill walks you through these checks interactively. The same data backs both surfaces.

Part 1 — SDK error codes

The table below is generated directly from the SDK’s published error catalog. If a row is missing, your installed version of @vektis-io/tracker predates that error code — upgrade and the row will appear.

Code	What it means	Most likely cause	What to try
VEK_TRK_INVALID_API_KEY	Vektis SDK disabled: API key was rejected (401).	API key was revoked or rotated in vektis.io	Generate a new key at vektis.io/settings/api-keys and call vektis.init() again.
VEK_TRK_VALIDATION_FAILED	Server rejected the event batch with a 400 (validation failed).	feature.* event missing required feature_id	Inspect the rejected batch in debug mode; check property caps and feature_id requirements.
VEK_TRK_RATE_LIMITED	Rate limited by the server (429). Backing off and retrying.	Bursty event volume exceeded the per-key limit (10000/min)	If this persists, reduce flush frequency or check for runaway track() calls.
VEK_TRK_SERVER_ERROR	Server returned 5xx. Backing off and retrying.	Transient server error	Check status.vektis.io for incidents. Events are queued and retried with backoff.
VEK_TRK_BATCH_TOO_LARGE	Server rejected the batch with 413 (too large). Batch dropped.	Single event has properties exceeding 8KB cap	Reduce property payload sizes. The SDK pre-splits at 480KB; hitting this is a defect signal.
VEK_TRK_NETWORK_ERROR	Network request to events.vektis.io failed.	Content Security Policy blocks the request	Verify CSP allows connect-src https://events.vektis.io. Check ad blockers and corporate proxies.
VEK_TRK_MISSING_IDENTITY	track() called before identify(). Event dropped.	identify() never called	Call vektis.identify({ customer_id }) before any track() calls.
VEK_TRK_INIT_TWICE	init() called twice. Subsequent calls are ignored.	Component re-renders triggering init in an effect	Initialize the SDK once at app startup. Use reset() to clear state between sessions.
VEK_TRK_IDENTIFY_BEFORE_INIT	identify() called before init(). Queued for replay.	Auth provider resolves before app-level init	This is non-fatal — the call is replayed once init() runs. Reorder if you can.
VEK_TRK_PROPS_CAP_EXCEEDED	Event properties exceed validation caps.	Logging an entire object as a property (stringify exceeds 1024)	Caps: 50 keys max, 64-char keys, 1024-char string values, 8KB total. Trim before sending.
VEK_TRK_TEST_KEY_NON_LOCAL	Test API key (vk_test_) used on a non-local hostname.	Wrong env var wired in production	Use vk_live_ on production hostnames; vk_test_ is for setup verification on localhost.
VEK_TRK_LIVE_KEY_LOCAL	Live API key (vk_live_) used on a local hostname.	Production .env loaded in local dev	Use vk_test_ for local development to avoid dirtying production analytics.
VEK_TRK_PREWARM_FAILED	OPTIONS preflight prewarm failed. sendBeacon may degrade on first unload.	Endpoint not reachable yet (DNS, proxy)	Verify CSP and that the endpoint is reachable. Fetch path still works; only first-session unload events are at risk.
VEK_TRK_PRE_INIT_QUEUE_OVERFLOW	Pre-init queue exceeded 1000 entries. Oldest events dropped.	Tracking events fired in a long pre-init bootstrap path	Call init() earlier in the app lifecycle.

Note

Each row is anchorable. The SDK’s docsAnchor field on every error entry points at the corresponding row in this table — clicking through from a console warning will scroll directly to the matching row.

Part 2 — Install-time and app-level issues

These scenarios aren’t surfaced as SDK error codes because they happen outside the SDK itself — in your install flow, in the VEKTIS app, or in the surrounding tooling.

The install wizard’s “still listening” step never advances

Symptom: You finished the install wizard, but Step 5 keeps showing “still listening for your first event” indefinitely even though you can see the events arriving in your dashboard.

Most likely cause: The wizard’s automatic event-presence check is temporarily unavailable. It’s a soft dependency — your install is fine, the wizard just can’t confirm it.

What to try:

• Open your VEKTIS dashboard directly and confirm the event(s) you sent are visible
• If they are, you can safely close the wizard — the install is complete
• If they’re not, check the SDK’s getStatus() in the browser console and follow the matching error code in Part 1

The first-run banner on /dev never goes away

Symptom: You’ve installed the SDK and confirmed events are arriving, but the dashboard banner asking you to install the tracker is still showing.

Most likely cause: Either the same event-presence check above is unavailable, or the banner’s local dismissal flag was cleared.

What to try:

• Hard-refresh the page (the banner is dismissed once events are confirmed — a stale browser state may still be showing it)
• Click the banner’s dismiss control directly if available
• Verify events are arriving in your dashboard — if they are, the banner will hide automatically the next time the dashboard re-checks

A dev item’s “Tracking Setup” card persists after install

Symptom: You’ve installed the SDK, your events are visible in the dashboard, but a specific dev item still shows the “Tracking Setup needed” card.

Most likely cause: The dev item’s data source hasn’t yet been promoted from manual to automated. This happens during the next analytics sync.

What to try:

• Wait a few minutes — the promotion runs on a short cadence
• Send at least one feature.used event whose feature_id matches the dev item
• Re-open the dev item; if the card is still showing, contact support so the data source can be promoted manually

CLI sign-in via the install skill fails to open the browser

Symptom: You ran claude /vektis-install. It says “Opening your browser to authorize…” — but no browser opens, or the browser hangs on a blank page.

Most likely cause: No display server (you’re on a headless box or SSH session), a corporate firewall blocks vektis.io, or your default browser is misconfigured.

What to try:

• Re-run the skill with the --paste-token flag — this falls back to a manual flow where you sign in on a different machine, generate a CLI token from the CLI tokens settings page, and paste it into the terminal
• If you can reach vektis.io in any browser on any machine, the paste-token fallback will work

Skills not appearing in Claude Code after running install-skills

Symptom: You ran npx @vektis-io/tracker install-skills and it printed a success message, but claude /vektis-install (or any other /vektis-* skill) doesn’t appear in your editor’s slash-command list.

Most likely cause: The script wrote the skills to a different directory than the one Claude Code is looking at. Common reasons: your project doesn’t have a .claude/ directory yet, you ran the command from inside node_modules/, or the project-root walk landed in the wrong directory in a monorepo.

What to try:

• Check the install actually created the files: ls .claude/skills/ from your project root should list vektis-install/ and friends. If .claude/skills/ doesn’t exist, re-run with --create: npx @vektis-io/tracker install-skills --create
• Run the command from your project root, not from inside node_modules/ or a sub-package. In a monorepo, run it from the workspace root rather than a package directory
• Restart Claude Code (or reload your editor’s slash-command index) after a successful install — most editors only pick up new skills on next launch
• See the installing the skills guide for the full install + authentication walkthrough

Related

• Per-framework guides — install instructions for Next.js, Vite, CRA, Nuxt, SvelteKit, vanilla
• Installing the skills — get the Claude Code skills into your project
• Configure CSP — required if your app sends Content-Security-Policy headers
• Reset on logout