Troubleshooting - su-record/vibe GitHub Wiki

Troubleshooting

Solutions to common issues when using Vibe.

Table of Contents

  1. Installation Issues
  2. MCP Server Issues
  3. Command Execution Issues
  4. Agent Issues
  5. Performance Issues
  6. Configuration Issues
  7. Platform-Specific Issues

Installation Issues

Issue 1: npm install -g @su-record/vibe fails

Symptoms:

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied

Cause: No permission to write to global npm directory.

Solution 1: Use sudo (not recommended)

sudo npm install -g @su-record/vibe

Solution 2: Fix npm permissions (recommended)

# Create npm directory in home folder
mkdir ~/.npm-global

# Configure npm to use new directory
npm config set prefix '~/.npm-global'

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

# Reinstall
npm install -g @su-record/vibe

Solution 3: Use nvm (best practice)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node via nvm
nvm install 18
nvm use 18

# Now install Vibe
npm install -g @su-record/vibe

Issue 2: vibe: command not found after installation

Symptoms:

npm install -g @su-record/vibe
# Success!

vibe --version
# bash: vibe: command not found

Cause: npm global bin directory not in PATH.

Solution:

# Find npm global bin path
npm config get prefix
# Example output: /usr/local

# Add to PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
vibe --version

Issue 3: Node version incompatibility

Symptoms:

npm install -g @su-record/vibe
# error: Requires Node.js >= 18.0.0

Cause: Node.js version too old.

Solution:

# Check current version
node --version

# If < 18.0.0, update Node
# Using nvm (recommended):
nvm install 18
nvm use 18

# Or download from nodejs.org:
# https://nodejs.org/en/download/

# Verify
node --version  # Should be 18.0.0+

# Reinstall Vibe
npm install -g @su-record/vibe

MCP Server Issues

Issue 4: MCP server not connected

Symptoms:

claude mcp list
# No MCP servers configured
# OR
# vibe: node /path/to/@su-record/vibe/node_modules/@su-record/hi-ai/dist/index.js - ✗ Disconnected

Cause 1: You're not in a project directory where vibe init was run.

Solution 1: Check your directory

# MCP servers are registered per-project
# Make sure you're in the correct project directory
cd /path/to/your/project

# Check if .vibe exists
ls -la .vibe/

# Run vibe init if needed
vibe init

# Verify
claude mcp list

Cause 2: Claude Code not running.

Solution 2: Start Claude Code

# Make sure Claude Code is open
# Check in menu bar or taskbar

Cause 3: MCP server registration corrupted.

Solution 3: Re-register

# In your project directory
cd /path/to/your/project

# Re-run init (safe to run multiple times)
vibe init

# Verify
claude mcp list
# Should show: vibe - ✓ Connected

Issue 5: Slash commands not working

Symptoms:

/vibe.spec "feature"
# Command not recognized

Cause: MCP server not connected or slash commands not registered.

Solution:

# 1. Check you're in your project directory
cd /path/to/your/project

# 2. Check MCP server status
claude mcp list
# If not connected, see Issue 4

# 3. Restart Claude Code
# Quit completely and reopen

# 4. Try command again
/vibe.spec "test feature"

Issue 6: MCP tools timeout

Symptoms:

vibe analyze --code
# Error: MCP tool 'analyze_complexity' timed out after 30s

Cause: Large codebase or slow disk I/O.

Solution 1: Increase timeout Edit .vibe/config.json:

{
  "mcp": {
    "timeout": 60000  // 60 seconds (default: 30000)
  }
}

Solution 2: Analyze specific directory

# Instead of entire project
vibe analyze --code src/services/

Solution 3: Exclude large files Create .vibeignore:

node_modules/
dist/
build/
*.min.js
vendor/

Command Execution Issues

Issue 7: vibe spec hangs on questions

Symptoms:

vibe spec "feature"
# Q1. Why?
# [cursor blinks forever, no response]

Cause: Interactive mode waiting for input.

Solution 1: Enter answer

# Just type your answer and press Enter
Q1. Why?
> Reduce user churn from 15% to 10%

Solution 2: Use batch mode

# Create answers file
cat > answers.json << 'EOF'
{
  "why": "Reduce churn...",
  "who": "All users...",
  "what": "Features...",
  "how": "Technical requirements...",
  "when": "Timeline...",
  "with_what": "Tech stack..."
}
EOF

# Run in batch mode
vibe spec "feature" --file answers.json --batch

Solution 3: Use slash command in Claude Code

/vibe.spec "feature"
# Claude will ask questions in chat

Issue 8: Task execution fails with "Agent not found"

Symptoms:

vibe run "Task 1-1"
# Error: Agent 'backend-nodejs-expert' not found

Cause: CLAUDE.md specifies unsupported tech stack.

Solution:

# Check supported agents
vibe agents

# Update CLAUDE.md with supported stack
# Supported:
# - Backend: Python/FastAPI
# - Frontend: Flutter, React/Next.js
# - Database: PostgreSQL

# Edit CLAUDE.md
vim CLAUDE.md

# Change:
# - Framework: Node.js/Express
# To:
# - Framework: FastAPI 0.104+

# Retry
vibe run "Task 1-1"

Issue 9: Task shows ✅ but code wasn't changed

Symptoms:

vibe run "Task 1-1"
# ✅ Task 1-1 completed

git diff
# (no output)

Cause: Task might be verification-only or agent encountered error but marked complete anyway.

Solution:

# Check task guide
cat .vibe/guides/task-1-1.md

# Check quality report
cat .vibe/reports/verification-*.md

# If task should have changed files, re-run with verbose
vibe run "Task 1-1" --verbose

# Look for errors in output

# If still failing, file issue:
# https://github.com/su-record/vibe/issues

Issue 10: "SPEC not found" error

Symptoms:

vibe plan "notification settings"
# Error: SPEC file not found: .vibe/specs/notification-settings.md

Cause: Mismatch between feature name and SPEC filename.

Solution:

# Check existing SPECs
ls .vibe/specs/

# Example output:
# notification_settings.md  (underscore, not hyphen)

# Use exact filename (without .md)
vibe plan "notification_settings"

# Or rename file
mv .vibe/specs/notification_settings.md \
   .vibe/specs/notification-settings.md

# Then retry
vibe plan "notification-settings"

Agent Issues

Issue 11: Agent uses wrong tech stack

Symptoms:

vibe run "Task 1-1"
# Agent suggests Express.js code
# But project uses FastAPI

Cause: CLAUDE.md missing or incorrect.

Solution:

# Create CLAUDE.md
cat > CLAUDE.md << 'EOF'
# CLAUDE.md

## Tech Stack

### Backend
- Framework: FastAPI 0.104+
- Database: PostgreSQL 17

### Frontend
- Framework: Flutter 3.24+
EOF

# Retry task
vibe run "Task 1-1"

Issue 12: Agent generates low-quality code

Symptoms:

vibe verify "feature"
# Code Quality: 45/100 (F)
# - No type hints
# - No docstrings
# - High complexity

Cause: Quality standards not configured.

Solution:

# Edit config
vim .vibe/config.json

# Add quality standards
{
  "quality": {
    "max_complexity": 10,
    "max_function_length": 20,
    "min_test_coverage": 80,
    "require_type_hints": true,
    "require_docstrings": true
  }
}

# Re-run task
vibe run "Task 1-1"

# Agent will now enforce standards

Issue 13: Agent doesn't follow project patterns

Symptoms:

Agent creates UserService.get_user()
But project uses UserRepository.find_by_id()

Cause: Agent doesn't know project patterns.

Solution:

# Create custom skill
mkdir -p skills/custom/
cat > skills/custom/project-patterns.md << 'EOF'
# Project Patterns

## Repository Pattern
Always use Repository suffix:
- UserRepository, not UserService
- Method names: find_by_id, find_all, save, delete

## Example
```python
class UserRepository:
    async def find_by_id(self, user_id: UUID) -> User | None:
        ...

EOF

Re-run task

vibe run "Task 1-1"

Agent will follow custom patterns


---

## Performance Issues

### Issue 14: `vibe analyze` is very slow

**Symptoms:**
```bash
vibe analyze --code
# Takes 5+ minutes

Cause: Large codebase with many files.

Solution 1: Analyze specific directories

# Instead of entire project
vibe analyze --code src/services/
vibe analyze --code src/api/

Solution 2: Exclude files Create .vibeignore:

node_modules/
dist/
build/
coverage/
*.test.js
*.spec.ts

Solution 3: Use parallel execution Edit .vibe/config.json:

{
  "analysis": {
    "parallel": true,
    "max_workers": 4
  }
}

Issue 15: MCP server uses too much memory

Symptoms:

MCP server memory usage: 2GB+
System becomes slow

Cause: Large memory cache from previous sessions.

Solution:

# Clear MCP memory cache
rm -rf ~/.vibe/memory/*.db

# Restart MCP server
claude mcp restart vibe

# Set memory limits
# Edit .vibe/config.json:
{
  "mcp": {
    "memory": {
      "max_size_mb": 512,
      "auto_cleanup": true
    }
  }
}

Issue 16: Task execution is slow

Symptoms:

vibe run "Task 1-1"
# Takes 10+ minutes for simple task

Cause: Network latency or slow AI model.

Solution:

# Check network
ping api.anthropic.com

# If slow, check:
# 1. VPN disconnected?
# 2. Firewall blocking?
# 3. Proxy configured correctly?

# Generate guide offline, execute manually
vibe run "Task 1-1" --guide-only
cat .vibe/guides/task-1-1.md
# Implement manually following guide

Configuration Issues

Issue 17: Invalid config.json

Symptoms:

vibe run "Task 1-1"
# Error: Invalid configuration: unexpected token in JSON

Cause: Syntax error in config.json.

Solution:

# Validate JSON
cat .vibe/config.json | python -m json.tool

# If error, fix syntax
vim .vibe/config.json

# Or regenerate default config
rm .vibe/config.json
vibe init

# Retry
vibe run "Task 1-1"

Issue 18: CLAUDE.md not being read

Symptoms:

vibe plan "feature"
# Agent suggests wrong tech stack despite CLAUDE.md

Cause: CLAUDE.md in wrong location or incorrect format.

Solution:

# CLAUDE.md must be in project root
ls CLAUDE.md
# If not found, move it:
mv docs/CLAUDE.md ./CLAUDE.md

# Verify format
cat CLAUDE.md
# Must have:
# ## Tech Stack
# ### Backend
# - Framework: ...

# Retry
vibe plan "feature"

Platform-Specific Issues

Issue 19: Windows: vibe command not found

Symptoms (Windows PowerShell):

vibe --version
# 'vibe' is not recognized as an internal or external command

Cause: npm global bin not in PATH.

Solution:

# Find npm global prefix
npm config get prefix
# Example: C:\Users\YourName\AppData\Roaming\npm

# Add to PATH
$env:Path += ";C:\Users\YourName\AppData\Roaming\npm"

# Permanent: Add to System Environment Variables
# Settings → System → About → Advanced system settings
# → Environment Variables → Path → Edit
# Add: C:\Users\YourName\AppData\Roaming\npm

# Restart PowerShell

# Verify
vibe --version

Issue 20: macOS: MCP server permission denied

Symptoms (macOS):

claude mcp list
# vibe: Error: EACCES: permission denied

Cause: Node.js binary not allowed by Gatekeeper.

Solution:

# Allow Node.js in System Preferences
# System Preferences → Security & Privacy → General
# Click "Allow" next to Node.js message

# Or remove quarantine attribute
xattr -d com.apple.quarantine $(which node)

# Restart MCP server
claude mcp restart vibe

# Verify
claude mcp list

Issue 21: Linux: npm global install fails

Symptoms (Linux):

npm install -g @su-record/vibe
# EACCES: permission denied

Cause: No write access to /usr/local.

Solution:

# Option 1: Fix npm permissions
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Option 2: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

# Install Vibe
npm install -g @su-record/vibe

Getting Help

If your issue isn't listed here:

1. Check Logs

# Vibe logs
cat ~/.vibe/logs/latest.log

# MCP server logs
cat ~/.vibe/mcp.log

# Claude Code logs
# Help → Show Logs

2. Run with Verbose Mode

vibe run "Task 1-1" --verbose
vibe analyze --verbose

3. Search GitHub Issues

# Open browser
open https://github.com/su-record/vibe/issues

# Search for your error message
# Check closed issues too (might be already solved)

4. File a Bug Report

# Create issue with template:
# - Vibe version: vibe --version
# - Node version: node --version
# - OS: uname -a (Linux/Mac) or ver (Windows)
# - Error message: Full error output
# - Steps to reproduce: What commands you ran
# - Expected behavior: What should happen
# - Actual behavior: What happened instead

Template:

## Bug Report

**Vibe Version:** 0.1.2
**Node Version:** 18.17.0
**OS:** macOS 14.0

**Error Message:**

vibe run "Task 1-1" Error: Agent not found


**Steps to Reproduce:**
1. vibe init
2. vibe spec "feature"
3. vibe plan "feature"
4. vibe tasks "feature"
5. vibe run "Task 1-1"

**Expected:** Task should execute
**Actual:** Error: Agent not found

**Additional Context:**
CLAUDE.md contents: ...

5. Community Resources

Quick Troubleshooting Checklist

# 1. Verify installation
vibe --version

# 2. Check MCP server
claude mcp list

# 3. Verify Node version
node --version  # Should be 18+

# 4. Check CLAUDE.md exists
cat CLAUDE.md

# 5. Validate config
cat .vibe/config.json | python -m json.tool

# 6. Check file permissions
ls -la .vibe/

# 7. Review logs
cat ~/.vibe/logs/latest.log

# 8. Try verbose mode
vibe <command> --verbose

Still stuck? We're here to help!

← Back to Best Practices | Home

⚠️ **GitHub.com Fallback** ⚠️