Skip to content
VEKTIS

vektis-troubleshoot

vektis-troubleshoot diagnoses problems with the @vektis-io/tracker SDK. Give it an error code or describe the symptom, and it loads the SDK’s live error catalog at runtime and returns ranked hypotheses with concrete next steps.

Terminal window
# Code lookup
claude /vektis-troubleshoot VEK_TRK_INVALID_API_KEY


# Symptom lookup
claude /vektis-troubleshoot "events not arriving"

The skill is read-only and non-mutating. It diagnoses; it doesn’t fix. For mutating fixes (re-install the SDK, re-authenticate), it points you at the right sibling skill.

When to use this skill

Section titled “When to use this skill”
You’re in this situationUse this skill
Browser console shows a VEK_TRK_* error codevektis-troubleshoot <code>
Events aren’t arriving in your VEKTIS dashboardvektis-troubleshoot "events not arriving"
vektis.getStatus() shows state: 'DISABLED' or 'UNINITIALIZED'vektis-troubleshoot DISABLED
The dashboard says you’ve installed the SDK but you’re sure you haven’tApp-side issue — see troubleshooting
You don’t know if the issue is the SDK or the dashboardRun this skill first — it’ll tell you if the SDK is at fault

How it works

Section titled “How it works”

The skill never hardcodes error messages or codes. Every diagnosis comes from @vektis-io/tracker/errors — the SDK’s published catalog — loaded at runtime. This means the catalog is always in sync with the version of the SDK you have installed.

When you give it an error code that matches ^VEK_TRK_[A-Z_]+$, the skill looks it up directly. Anything else is treated as a free-form symptom and matched against every catalog entry’s message and hypothesis text.

Code-lookup output

Section titled “Code-lookup output”

For an exact code match, the skill prints:

Error: VEK_TRK_INVALID_API_KEY
Your API key was rejected by the VEKTIS server.


Action: Check that the key in your env file matches a key in your VEKTIS dashboard
under Settings → API & CLI tokens, and that it hasn't been rotated or deleted.


Likely causes (most likely first):
  1. The key was rotated or deleted in the VEKTIS dashboard.
  2. The key in your env file is from a different organization.
  3. The env var name doesn't match what the framework expects (e.g. NEXT_PUBLIC_VEKTIS_KEY vs VITE_VEKTIS_KEY).


Docs: /integrations/tracker/troubleshooting#vek-trk-invalid-api-key

Symptom-matching output

Section titled “Symptom-matching output”

For a free-form symptom, the skill ranks the top 2–3 catalog entries by token overlap and surfaces them in confidence order:

Top matches for "events not arriving":


1. VEK_TRK_NETWORK_ERROR  — likely match because: "events not arriving" overlaps with "network failure prevents events from being sent"
   Error: VEK_TRK_NETWORK_ERROR
   ... (full code-lookup output)


2. VEK_TRK_CSP_BLOCKED  — possible match because: "not arriving" overlaps with "browser blocks the request"
   Error: VEK_TRK_CSP_BLOCKED
   ... (full code-lookup output)


3. VEK_TRK_INVALID_API_KEY  — less likely, but consider if 1 and 2 don't apply:
   ... (full code-lookup output)

The skill caps at three matches to avoid overwhelming you. The rest are in the troubleshooting matrix.

Hard guarantees

Section titled “Hard guarantees”
  • No hardcoded error strings. The catalog is the single source of truth — load-and-diagnose.
  • No certainty claims. Output uses confidence-shaping language (“most likely”, “possible”, “less likely”). You decide what to investigate.
  • No external action. The skill never modifies code, configuration, or your auth state.
  • Catalog miss is a soft-fail. If your input doesn’t match any catalog entry, the skill points you at /integrations/tracker/troubleshooting rather than throwing.

What happens when something goes wrong

Section titled “What happens when something goes wrong”
SituationWhat the skill does
The SDK isn’t installed locallyFalls back to npx -y -p @vektis-io/tracker@^1.0.0 to fetch the catalog. Network required.
Both local and npx paths failPrints the catalog-miss message with a docs link. Never throws.
Your input doesn’t match any catalog entryPrints “No matching error in the catalog.” plus the docs link. The SDK may have shipped a new error since this skill was published — npm install @vektis-io/tracker@latest and try again.
Your input is too ambiguous (e.g., just “broken”)Prompts for more detail rather than emit a low-quality top-N.

What this skill does NOT do

Section titled “What this skill does NOT do”
  • Modify code, config, or env vars. (For SDK re-install: vektis-install.)
  • Re-authenticate. (Re-run any other skill — its auth step refreshes credentials.)
  • Diagnose dashboard-side issues. The SDK only knows about itself. For app-side issues like “I can’t see metrics on my Dev Item” or “post-release section is blank,” see app-side troubleshooting.
  • Look at your code. The skill diagnoses from error codes and symptoms, not from inspection. If you want a deeper look, paste the relevant code into chat after the skill’s output.
Section titled “Related”