Skip to content
VEKTIS

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.

Part 1 — SDK error codes

Section titled “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_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.
VEK_TRK_NON_PUBLISHABLE_KEY Browser SDK initialized with a non-publishable API key. Use a vk_pub_* key for browser code. Server-side key (vk_test_/vk_live_) accidentally shipped to the browser Generate a publishable key at vektis.io/settings/api-keys (scope: publishable) and call vektis.init() with that key.

Part 2 — Install-time and app-level issues

Section titled “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

Section titled “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

Section titled “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

Section titled “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
Section titled “Related”