Troubleshooting

This page covers common issues you might encounter with VibeKit and how to resolve them.

Installation Issues

Install Script Fails

Error: Failed to download vibekit

Solutions:

1. Check internet connection
2. Verify GitHub releases are accessible
3. Try manual installation

# Manual download
curl -L https://github.com/gabrielkuettel/vibekit/releases/latest/download/vibekit-linux-x64 -o vibekit
chmod +x vibekit
mv vibekit ~/.local/bin/

vibekit Not Found After Install

Error: command not found: vibekit

Solution: Add ~/.local/bin to PATH

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Setup Issues

AlgoKit Not Found

Error: AlgoKit CLI not found

Solution: Install AlgoKit

# macOS
brew install algorand/tap/algokit

# Linux/Windows - see AlgoKit docs

Docker Not Running (Vault)

Error: Cannot connect to Docker daemon

Solution:

# Start Docker
sudo systemctl start docker  # Linux
# Or start Docker Desktop

# Then restart Vault
vibekit vault start

Vault Issues

Vault Won’t Start

Error: Vault container failed to start

Solutions:

1. Check Docker is running
2. Check port 8200 is available
3. Remove old container

docker rm -f vibekit-vault
vibekit vault start

Vault Is Sealed

Error: Vault is sealed

Solution:

vibekit vault unseal

Lost Vault Token

If you lose the root token:

1. Check ~/.config/vibekit/vault-root-token
2. If truly lost, you may need to reset Vault:

# WARNING: This deletes all accounts
docker rm -f vibekit-vault
docker volume rm vibekit-vault-data
vibekit vault start

MCP Issues

MCP Server Not Starting

Error: Failed to start MCP server

Solutions:

1. Check vibekit path

which vibekit

2. Test MCP directly

vibekit mcp

3. Check configuration

cat .mcp.json  # or opencode.json

Tool Calls Failing

Error: Tool call failed: ...

Check:

1. LocalNet running: algokit localnet status
2. Provider available: vibekit status
3. Account funded: Ask AI to check balance

Kappa Not Responding

Error: Kappa MCP not available

Solution:

# Test Kappa directly
npx -y @kappaml/mcp-server-kappa@latest

# If fails, check npm/npx
npm -v
npx -v

Network Issues

LocalNet Not Running

Error: Connection refused or Network unavailable

Solution:

algokit localnet start
algokit localnet status

TestNet Funding Fails

Error: Dispenser error or Rate limited

Solutions:

1. Check auth: vibekit dispenser login
2. Wait for rate limit reset
3. Use LocalNet instead

Wrong Network

Error: Operations failing unexpectedly

Check:

# Ask AI
"What network am I on?"

# Switch if needed
"Switch to localnet"

Account Issues

No Accounts Found

Error: No accounts available

Solutions:

1. Check provider: vibekit status
2. Create account: Ask AI “Create a new account”
3. On LocalNet, KMD accounts may need creation

Account Not Funded

Error: Account below minimum balance

Solution:

Ask AI: "Fund my account with 10 ALGO"

Signing Failed

Error: Failed to sign transaction

Solutions:

1. Check correct account is active
2. Check provider is running/unsealed
3. Verify on correct network

Skills Issues

Skills Not Working

Error: AI doesn’t understand Algorand concepts

Solutions:

1. Check skills installed

ls ~/.config/opencode/skill/  # or ~/.claude/skills/

2. Re-install skills

vibekit init

Outdated Skills

Skills may become outdated. Re-run setup to update:

vibekit init

Getting Help

If you’re still stuck:

1. Check status: vibekit status
2. Check logs: Look for error messages in terminal
3. GitHub Issues: Report a bug

When reporting issues, include:

• VibeKit version (vibekit --version)
• Operating system
• Error messages
• Steps to reproduce