> ## Documentation Index
> Fetch the complete documentation index at: https://nikcli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<AccordionGroup>
  <Accordion title="Solution 1: Use npx (Recommended)">
    ```bash theme={null}
    # Use npx instead of global installation
    npx @nicomatt69/nikcli

    # Or create an alias
    echo 'alias nikcli="npx @nicomatt69/nikcli"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Solution 2: Fix npm Permissions">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Solution 3: Use Local Installation">
    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

### Problem: Node.js Version Issues

**Symptoms:**

* `Node.js version too old` error
* Features not working properly
* Compatibility issues

**Solutions:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

<AccordionGroup>
  <Accordion title="Check API Key Format">
    ```bash theme={null}
    # 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...
    ```
  </Accordion>

  <Accordion title="Test API Connectivity">
    ```bash theme={null}
    # Test API connection
    /debug

    # Check model availability
    /models

    # Verify API key validity
    /set-key anthropic sk-ant-api03-... --test
    ```
  </Accordion>

  <Accordion title="Environment Variables">
    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

### Problem: Rate Limiting

**Symptoms:**

* `Rate limit exceeded` errors
* Slow responses
* API quota exceeded

**Solutions:**

```bash theme={null}
# 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:**

<AccordionGroup>
  <Accordion title="Check Agent Status">
    ```bash theme={null}
    # Check agent status
    /agents

    # Restart agents
    /agent universal-agent --restart

    # Check agent metrics
    /agent universal-agent --metrics
    ```
  </Accordion>

  <Accordion title="Increase Timeout">
    ```bash theme={null}
    # Increase agent timeout
    /agent-config universal-agent --timeout 600

    # Set global timeout
    /config --timeout 600
    ```
  </Accordion>

  <Accordion title="Check Resources">
    ```bash theme={null}
    # Check memory usage
    /memory --stats

    # Check system resources
    /diagnostic

    # Restart NikCLI
    /quit
    nikcli
    ```
  </Accordion>
</AccordionGroup>

### Problem: Agent Tasks Failing

**Symptoms:**

* Tasks fail with errors
* Incomplete task execution
* Unexpected behavior

**Solutions:**

```bash theme={null}
# 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:**

<AccordionGroup>
  <Accordion title="Check Resource Usage">
    ```bash theme={null}
    # Monitor resources
    /parallel-monitor --resources

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

    # Check memory limits
    /memory --stats
    ```
  </Accordion>

  <Accordion title="Handle Dependencies">
    ```bash theme={null}
    # Check task dependencies
    /parallel --dependencies --validate

    # Simplify dependencies
    /parallel --strategy sequential "task1" "task2" "task3"
    ```
  </Accordion>

  <Accordion title="Recover from Hangs">
    ```bash theme={null}
    # Stop parallel execution
    /parallel --kill

    # Clear task queues
    /parallel-queue --clear

    # Restart with simpler tasks
    /parallel --strategy sequential "simple-task"
    ```
  </Accordion>
</AccordionGroup>

### Problem: Memory Issues

**Symptoms:**

* Out of memory errors
* Slow performance
* System crashes

**Solutions:**

```bash theme={null}
# 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:**

<AccordionGroup>
  <Accordion title="Check File Permissions">
    ```bash theme={null}
    # Check config directory permissions
    ls -la ~/.nikcli/

    # Fix permissions
    chmod 755 ~/.nikcli/
    chmod 644 ~/.nikcli/config.json
    ```
  </Accordion>

  <Accordion title="Reset Configuration">
    ```bash theme={null}
    # Reset to defaults
    /config --reset

    # Reconfigure settings
    /config --interactive
    ```
  </Accordion>

  <Accordion title="Manual Configuration">
    ```bash theme={null}
    # Edit config file directly
    nano ~/.nikcli/config.json

    # Or use environment variables
    export NIKCLI_CONFIG_PATH=~/.nikcli/config.json
    ```
  </Accordion>
</AccordionGroup>

### Problem: Mode Switching Issues

**Symptoms:**

* Cannot switch modes
* Mode not persisting
* Unexpected mode behavior

**Solutions:**

```bash theme={null}
# 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:**

<AccordionGroup>
  <Accordion title="Check File Permissions">
    ```bash theme={null}
    # Check file permissions
    ls -la filename

    # Fix permissions
    chmod 644 filename
    chmod 755 directory
    ```
  </Accordion>

  <Accordion title="Use Sandbox Mode">
    ```bash theme={null}
    # Enable sandbox mode
    /sandbox --enable

    # Configure file access
    /sandbox --allow-file-system
    /sandbox --restrict-paths "/home/user/projects"
    ```
  </Accordion>

  <Accordion title="Check Working Directory">
    ```bash theme={null}
    # Check current directory
    /run pwd

    # Change working directory
    /run cd /path/to/project

    # List directory contents
    /ls
    ```
  </Accordion>
</AccordionGroup>

### Problem: File Not Found Errors

**Symptoms:**

* File not found errors
* Path resolution issues
* Incorrect file paths

**Solutions:**

```bash theme={null}
# 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:**

<AccordionGroup>
  <Accordion title="Check Network Connection">
    ```bash theme={null}
    # Test network connectivity
    /run ping google.com

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

    # Test API endpoints
    /debug --network
    ```
  </Accordion>

  <Accordion title="Configure Proxy">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Use Local Models">
    ```bash theme={null}
    # Switch to local models
    /set-key ollama http://localhost:11434
    /model ollama:llama3.1:8b

    # Or use offline mode
    /config --offline-mode
    ```
  </Accordion>
</AccordionGroup>

## 🔍 Debugging Tools

### Diagnostic Commands

```bash theme={null}
# 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

```bash theme={null}
# Check performance metrics
/stats

# Monitor resource usage
/memory --stats
/cpu --stats

# Check agent performance
/agents --metrics

# View execution times
/parallel-monitor --performance
```

### Log Analysis

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Documentation" icon="book">
    [Complete Documentation](https://nikcli.mintlify.app)
  </Card>

  <Card title="Command Reference" icon="terminal">
    [All Commands](https://nikcli.mintlify.app/cli-reference/commands-overview)
  </Card>

  <Card title="Examples" icon="code">
    [Workflow Examples](https://nikcli.mintlify.app/examples/basic-workflows)
  </Card>

  <Card title="GitHub Issues" icon="github">
    [Report Bugs](https://github.com/nikomatt69/nikcli-main/issues)
  </Card>
</CardGroup>

### Community Support

```bash theme={null}
# Join Discord community
# https://discord.gg/nikcli

# Follow on Twitter
# @nikcli_dev

# Star on GitHub
# https://github.com/nikomatt69/nikcli-main
```

### Professional Support

```bash theme={null}
# Email support
# support@nikcli.dev

# Enterprise support
# enterprise@nikcli.dev

# Training and consulting
# training@nikcli.dev
```

## 🎯 Prevention Tips

### 1. Regular Maintenance

```bash theme={null}
# Update NikCLI regularly
npm update -g @nicomatt69/nikcli

# Clear caches periodically
/cache --clear

# Check configuration
/config --validate
```

### 2. Monitor Resources

```bash theme={null}
# Monitor memory usage
/memory --stats

# Check disk space
/run df -h

# Monitor CPU usage
/run top
```

### 3. Backup Configuration

```bash theme={null}
# Export configuration
/config --export backup-config.json

# Backup important files
/run cp -r ~/.nikcli ~/.nikcli-backup
```

## 🚀 Next Steps

<CardGroup cols={2}>
  <Card title="FAQ" icon="help-circle" href="/troubleshooting/faq">
    Common questions and answers
  </Card>

  <Card title="Command Reference" icon="terminal" href="/cli-reference/commands-overview">
    Complete command reference
  </Card>

  <Card title="Examples" icon="book" href="/examples/basic-workflows">
    Learn through examples
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/nikomatt69/nikcli-main/issues">
    Report bugs and request features
  </Card>
</CardGroup>

<Tip>
  **Pro Tip:** Use `/diagnostic` regularly to catch issues early. This command checks all system components and provides recommendations for optimization.
</Tip>