GitHub ★Get kits →

Troubleshooting

Quick fixes for common issues. Most resolve in under 5 minutes — every fix below uses a real vk command.

Quick Diagnosis

Match your symptom to a category below, then jump to that section for the fix.

  • vk: command not found or install fails → Installation Issues
  • /vk:… does nothing or is not found → Command Errors
  • Agent (planner, tester, reviewer, debugger) not activating → Agent Issues
  • GitHub auth error or download blocked → API Key Setup
  • vk init is slow or hanging → Performance Issues

Installation Issues

Problems installing or running the vk command after a global install.

vk: command not found

The npm global bin directory is not on your PATH, so your shell cannot find the vikit-cli executable after a global install.

npm config get prefix # find your global bin prefix # add <prefix>/bin to your PATH, then: npm install -g vikit-cli vk --version

Permission denied on global install (EACCES)

Your npm global directory is root-owned, so the global install fails with EACCES. Fix the npm prefix rather than using sudo.

mkdir ~/.npm-global npm config set prefix '~/.npm-global' # add ~/.npm-global/bin to your PATH, then: npm install -g vikit-cli # or, with bun: bun add -g vikit-cli

Install blocked by wrong Node version

vikit-cli requires Node.js 18 or newer. An older runtime blocks the install or causes runtime errors.

node --version # upgrade to Node.js 18+ if older, then reinstall

vk init hangs during download

vk init downloads from GitHub. If GitHub is not authenticated or your token lacks the repo scope, the download stalls. Authenticate, then re-run — init is safe to re-run.

gh auth login # preferred — auto-detected by vk # or: export GITHUB_TOKEN=ghp_xxx # token needs the 'repo' scope vk init -g --kit engineer

Stale or odd behavior after update

An outdated CLI can produce confusing behavior. Update the CLI, then re-run install.

vk update vk init -g

Command Errors

A /vk:… slash command does nothing or is reported as not found.

/vk:eng:plan not found

The skill is installed at the wrong scope — global versus the current project. Check where the skills directory is populated, then reinstall at the scope you intend to use.

ls ~/.claude/skills/ # global install ls ./.claude/skills/ # project-local install vk init -g # reinstall globally for every project

Skills directory empty after install

A previous install did not complete. Re-run init for the engineer kit and verify the skills directory.

vk init -g --kit engineer ls ~/.claude/skills/

Skill command present but broken

The skill file is present but its SKILL.md frontmatter is malformed, so the command fails to load. Re-run install to restore it.

vk doctor --fix

settings.json did not merge

A config merge conflict prevented settings.json from updating. Let vk doctor repair the merge.

vk doctor --fix

Agent Issues

A specialist agent (planner, tester, reviewer, debugger) is missing or not activating.

Agent is missing (planner, tester, reviewer, debugger)

The agents directory is missing or an agent file is malformed. Re-run a global install to restore every agent.

ls ~/.claude/agents/*.md vk init -g

Agent present but inactive

The agent file exists but Claude Code is not running in the right place. Global agents require a global install and a running Claude Code session inside your project.

claude --version # launch claude inside your project directory

API Key Setup

Authentication errors. vikit is GitHub-PAT-first: a token with the repo scope is REQUIRED. GEMINI_API_KEY is optional and only for the ai-multimodal skill.

GitHub token not found or download fails

GitHub is not authenticated: gh is not logged in, GH_TOKEN/GITHUB_TOKEN is unset, or the OS keychain has no entry. Authenticate, then re-run init.

gh auth login # preferred — auto-detected by vk # or: export GITHUB_TOKEN=ghp_xxx vk init -g --kit engineer

401 or 403 from GitHub

Your token expired or lacks the repo scope. Regenerate a PAT with the repo scope and re-authenticate.

# regenerate a PAT with the 'repo' scope, then: gh auth login # or: export GITHUB_TOKEN=ghp_xxx

GEMINI_API_KEY not found

This optional key is needed only by the ai-multimodal skill. Set it if you use image, video, or audio analysis features.

export GEMINI_API_KEY=xxx # only for ai-multimodal

Performance Issues

Slow installs, rate limits, and concerns about duplicate files.

vk init is slow

vk init pulls large downloads, so a slow connection stretches the wait. It is safe to re-run, and vk doctor can confirm any partial state.

vk doctor vk init -g --kit engineer

GitHub rate-limit errors

Unauthenticated GitHub requests hit a low rate limit. Authenticating raises the ceiling.

gh auth login

Worried vk init duplicates files

It won't. vk init merges cleanly and preserves your customizations — no duplicates. Run vk doctor to confirm a healthy state.

vk doctor

Common Quick Fixes

Reset, verify, and update in one place.

# Reset / restore vk uninstall # remove managed files (recover with vk backups) vk init -g --kit engineer # reinstall the engineer kit # Verify setup vk --version claude --version ls ~/.claude/skills/ # global skills present vk doctor # full health check # Update vk update # CLI to latest vk init -g # packages to latest release

Still Stuck

Generate a shareable diagnostics report, then gather the details someone needs to help you.

  • Report an issue with your OS, vk --version, claude --version, the full error text, and repro steps.
  • Run /vk:eng:fix inside Claude Code to auto-diagnose and repair common setup problems.
  • Use vk backups to recover managed files before any destructive change.
vk doctor --report # shareable diagnostics

Prevention Tips

A few habits keep vikit healthy.

  • Do: keep vikit updated — run vk update and vk init regularly.
  • Do: run vk doctor whenever something feels off.
  • Do: authenticate with gh auth login to avoid GitHub rate limits.
  • Do: read error messages in full — they usually name the fix.
  • Don't: hand-edit vikit-managed files under .claude/ — they are overwritten on vk init.
  • Don't: skip vk update before reporting an issue.
  • Don't: delete the .claude/ directory to 'reset' — use vk uninstall and vk init instead.

More Fixes

Deep dives for setup and every CLI command.