Skip to main content

​
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 errors
  • Cannot install globally
  • Permission errors when running commands
Solutions: 
# 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

# 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 error
  • Features 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 errors
  • Models not available
  • Authentication failures
Solutions: 
# Verify API key format
/config

# Re-set API key with correct format
/set-key anthropic sk-ant-api03-...
/set-key openai sk-...
/set-key google AIza...

# 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 errors
  • Slow 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

# Set proxy settings
/config --proxy http://proxy.company.com:8080

# Or use environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Switch to local models
/set-key ollama http://localhost:11434
/model ollama:llama3.1:8b

# Or use offline mode
/config --offline-mode

​
🔍 Debugging Tools

​
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

​
Performance Monitoring

# 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

Command Reference

All Commands

GitHub Issues

Report Bugs

​
Community Support

# 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
# [email protected]

# Enterprise support
# [email protected]

# Training and consulting
# [email protected]

​
🎯 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

FAQ

Common questions and answers

Command Reference

Complete command reference

Examples

Learn through examples

GitHub Issues

Report bugs and request features
Pro Tip: Use /diagnostic regularly to catch issues early. This command checks all system components and provides recommendations for optimization.