Common Issues & Solutions Get help with common NikCLI problems and learn how to troubleshoot issues effectively.
🚨 Installation Issues Problem: Permission Denied During Installation Symptoms:
EACCES: permission denied errorsCannot install globally
Permission errors when running commands
Solutions:
Solution 1: Use npx (Recommended)
# Use npx instead of global installation npx @nicomatt69/nikcli # Or create an alias echo 'alias nikcli="npx @nicomatt69/nikcli"' >> ~/.bashrc source ~/.bashrc
Solution 2: Fix npm Permissions
# Create a directory for global packages mkdir ~/.npm-global npm config set prefix '~/.npm-global' # Add to PATH echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc # Install NikCLI npm install -g @nicomatt69/nikcli
Solution 3: Use Local Installation
# Install locally in your project npm install @nicomatt69/nikcli # Run with npx npx nikcli # Or add to package.json scripts echo '"scripts": {"nikcli": "nikcli"}' >> package.json npm run nikcli Problem: Node.js Version Issues Symptoms:
Node.js version too old errorFeatures not working properly
Compatibility issues
Solutions: # Check Node.js version node --version # Update Node.js using nvm (recommended) nvm install 18 nvm use 18 # Or download from nodejs.org # https://nodejs.org/ # Verify installation nikcli --version Problem: Package Manager Conflicts Symptoms:
Multiple package managers causing conflicts
Installation fails with different package managers
Inconsistent behavior
Solutions: # Clear all caches npm cache clean --force yarn cache clean pnpm store prune # Use specific package manager curl -fsSL https://raw.githubusercontent.com/nikomatt69/nikcli-main/main/installer/install.sh | bash -s npm # Or force specific manager npm install -g @nicomatt69/nikcli --force 🔑 API Key Issues Problem: API Keys Not Working Symptoms:
Invalid API key errorsModels not available
Authentication failures
Solutions:
# Test API connection /debug # Check model availability /models # Verify API key validity /set-key anthropic sk-ant-api03-... --test
# Set environment variables export ANTHROPIC_API_KEY = "sk-ant-api03-..." export OPENAI_API_KEY = "sk-..." export GOOGLE_API_KEY = "AIza..." # Or create .env file echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > .env echo "OPENAI_API_KEY=sk-..." >> .env Problem: Rate Limiting Symptoms:
Rate limit exceeded errorsSlow responses
API quota exceeded
Solutions: # Check current usage /tokens # Switch to different model /model claude-3-5-sonnet /model gpt-4o-mini # Reduce concurrency /parallel-config --max-concurrent 2 # Use local models /set-key ollama http://localhost:11434 /model ollama:llama3.1:8b 🤖 Agent Issues Problem: Agent Not Responding Symptoms:
Agent commands hang
No response from agents
Timeout errors
Solutions:
# Check agent status /agents # Restart agents /agent universal-agent --restart # Check agent metrics /agent universal-agent --metrics
# Increase agent timeout /agent-config universal-agent --timeout 600 # Set global timeout /config --timeout 600
# Check memory usage /memory --stats # Check system resources /diagnostic # Restart NikCLI /quit nikcli Problem: Agent Tasks Failing Symptoms:
Tasks fail with errors
Incomplete task execution
Unexpected behavior
Solutions: # Check task history /agent universal-agent --history # Enable debug mode /agent universal-agent --debug # Check error logs /logs --level debug # Retry failed task /agent universal-agent --retry task-id ⚡ Parallel Execution Issues Problem: Parallel Tasks Hanging Symptoms:
Parallel tasks not completing
Resource exhaustion
Deadlocks
Solutions:
# Monitor resources /parallel-monitor --resources # Reduce concurrency /parallel-config --max-concurrent 2 # Check memory limits /memory --stats
# Check task dependencies /parallel --dependencies --validate # Simplify dependencies /parallel --strategy sequential "task1" "task2" "task3"
# Stop parallel execution /parallel --kill # Clear task queues /parallel-queue --clear # Restart with simpler tasks /parallel --strategy sequential "simple-task" Problem: Memory Issues Symptoms:
Out of memory errors
Slow performance
System crashes
Solutions: # Check memory usage /memory --stats # Reduce memory limits /parallel-config --memory-limit 1GB # Clear caches /cache --clear # Restart NikCLI /quit nikcli 🔧 Configuration Issues Problem: Configuration Not Saving Symptoms:
Settings not persisting
Configuration reset on restart
Permission errors
Solutions:
# Check config directory permissions ls -la ~/.nikcli/ # Fix permissions chmod 755 ~/.nikcli/ chmod 644 ~/.nikcli/config.json
# Reset to defaults /config --reset # Reconfigure settings /config --interactive
# Edit config file directly nano ~/.nikcli/config.json # Or use environment variables export NIKCLI_CONFIG_PATH =~ /. nikcli / config . json Problem: Mode Switching Issues Symptoms:
Cannot switch modes
Mode not persisting
Unexpected mode behavior
Solutions: # Check current mode /mode # Force mode switch /default --force /plan --force /auto --force # Reset mode settings /mode --reset # Check mode configuration /mode --config 📁 File Operation Issues Problem: File Permission Errors Symptoms:
Cannot read/write files
Permission denied errors
File access issues
Solutions:
# Check file permissions ls -la filename # Fix permissions chmod 644 filename chmod 755 directory
# Enable sandbox mode /sandbox --enable # Configure file access /sandbox --allow-file-system /sandbox --restrict-paths "/home/user/projects"
# Check current directory /run pwd # Change working directory /run cd /path/to/project # List directory contents /ls Problem: File Not Found Errors Symptoms:
File not found errors
Path resolution issues
Incorrect file paths
Solutions: # Check file existence /ls /find-files "filename" # Use absolute paths /read /full/path/to/file # Check working directory /run pwd # Search for files /search "filename" 🌐 Network Issues Problem: Network Connectivity Symptoms:
Cannot connect to APIs
Timeout errors
Network unreachable
Solutions:
# Test network connectivity /run ping google.com # Check DNS resolution /run nslookup api.anthropic.com # Test API endpoints /debug --network
# Switch to local models /set-key ollama http://localhost:11434 /model ollama:llama3.1:8b # Or use offline mode /config --offline-mode Diagnostic Commands # Run full diagnostics /diagnostic # Check system status /monitor # View detailed logs /logs --level debug # Check configuration /config --validate # Test all components /debug --full # Check performance metrics /stats # Monitor resource usage /memory --stats /cpu --stats # Check agent performance /agents --metrics # View execution times /parallel-monitor --performance Log Analysis # View recent logs /logs --tail 100 # Filter logs by level /logs --level error # Search logs /logs --search "error" # Export logs /logs --export debug.log 🆘 Getting Help Self-Help Resources # Join Discord community # https://discord.gg/nikcli # Follow on Twitter # @nikcli_dev # Star on GitHub # https://github.com/nikomatt69/nikcli-main Professional Support # Email support # support@nikcli.dev # Enterprise support # enterprise@nikcli.dev # Training and consulting # training@nikcli.dev 🎯 Prevention Tips 1. Regular Maintenance # Update NikCLI regularly npm update -g @nicomatt69/nikcli # Clear caches periodically /cache --clear # Check configuration /config --validate 2. Monitor Resources # Monitor memory usage /memory --stats # Check disk space /run df -h # Monitor CPU usage /run top 3. Backup Configuration # Export configuration /config --export backup-config.json # Backup important files /run cp -r ~/.nikcli ~/.nikcli-backup 🚀 Next Steps Pro Tip: Use /diagnostic regularly to catch issues early. This command checks all system components and provides recommendations for optimization.
