Common Issues

Solve common problems and get help with NikCLI troubleshooting

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:

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 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:

Check API Key Format

# 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 Connectivity

# Test API connection
/debug

# Check model availability
/models

# Verify API key validity
/set-key anthropic sk-ant-api03-... --test

Environment Variables

# 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

# Check agent status
/agents

# Restart agents
/agent universal-agent --restart

# Check agent metrics
/agent universal-agent --metrics

Increase Timeout

# Increase agent timeout
/agent-config universal-agent --timeout 600

# Set global timeout
/config --timeout 600

Check Resources

# 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:

Check Resource Usage

# Monitor resources
/parallel-monitor --resources

# Reduce concurrency
/parallel-config --max-concurrent 2

# Check memory limits
/memory --stats

Handle Dependencies

# Check task dependencies
/parallel --dependencies --validate

# Simplify dependencies
/parallel --strategy sequential "task1" "task2" "task3"

Recover from Hangs

# 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 File Permissions

# Check config directory permissions
ls -la ~/.nikcli/

# Fix permissions
chmod 755 ~/.nikcli/
chmod 644 ~/.nikcli/config.json

Reset Configuration

# Reset to defaults
/config --reset

# Reconfigure settings
/config --interactive

Manual Configuration

# 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

# Check file permissions
ls -la filename

# Fix permissions
chmod 644 filename
chmod 755 directory

Use Sandbox Mode

# Enable sandbox mode
/sandbox --enable

# Configure file access
/sandbox --allow-file-system
/sandbox --restrict-paths "/home/user/projects"

Check Working Directory

# 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:

Check Network Connection

# Test network connectivity
/run ping google.com

# Check DNS resolution
/run nslookup api.anthropic.com

# Test API endpoints
/debug --network

Configure Proxy

# 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

Use Local Models

# 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

Documentation

Complete Documentation

Command Reference

All Commands

Examples

Workflow Examples

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
# [e-mail]

# Enterprise support
# [e-mail]

# Training and consulting
# [e-mail]

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