> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-05-13
title: Troubleshooting
category: CLI
description: Common issues and solutions for the AGNT5 CLI
hideRightSidebar: true
---

Common issues and solutions when using the AGNT5 CLI.


**Diagnostic commands**: `agnt5 --version`, `agnt5 auth whoami`, `agnt5 context`
**Common failure modes**: missing CLI on PATH (`command not found`); missing/expired credentials; Docker daemon unreachable; wrong context for the target environment
**Reset paths**: re-run `agnt5 auth login` to refresh credentials; `agnt5 context use <name>` to switch environment; reinstall via the platform's install method to fix PATH issues


## Installation Issues

### Command Not Found

**Problem**: `agnt5: command not found` after installation.

**Solutions**:
1. **Check if npm global packages are in PATH**:
   ```bash
   npm config get prefix
   echo $PATH
   ```

2. **Reinstall the CLI**:
   ```bash
   npm uninstall -g agnt5
   npm install -g agnt5
   ```

3. **Use npx as alternative**:
   ```bash
   npx agnt5 --version
   ```

4. **Add npm global bin to PATH** (if missing):
   ```bash
   # Add to ~/.bashrc or ~/.zshrc
   export PATH=$PATH:$(npm config get prefix)/bin
   ```

### Permission Denied

**Problem**: Permission errors during installation on macOS/Linux.

**Solutions**:
1. **Use a Node version manager** (recommended):
   ```bash
   # Install nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 18
   nvm use 18
   npm install -g agnt5
   ```

2. **Change npm's default directory**:
   ```bash
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc
   npm install -g agnt5
   ```

3. **Use sudo** (not recommended):
   ```bash
   sudo npm install -g agnt5
   ```

### Windows Installation Issues

**Problem**: Installation fails on Windows.

**Solutions**:
1. **Run as Administrator**:
   - Right-click Command Prompt/PowerShell
   - Select "Run as Administrator"
   - Run installation command

2. **Use Windows Subsystem for Linux (WSL)**:
   ```bash
   wsl --install
   # Then install in WSL environment
   ```

3. **Use Chocolatey**:
   ```bash
   choco install nodejs
   npm install -g agnt5
   ```

## Authentication Issues

### Invalid API Key

**Problem**: "Invalid API key" or "Unauthorized" errors.

**Solutions**:
1. **Verify your API key**:
   ```bash
   agnt5 config get api-key
   ```

2. **Reset and re-enter API key**:
   ```bash
   agnt5 config set api-key your-new-api-key
   ```

3. **Use interactive login**:
   ```bash
   agnt5 auth login
   ```

4. **Check environment variables**:
   ```bash
   echo $AGNT5_API_KEY
   ```

### Token Expired

**Problem**: Authentication token has expired.

**Solutions**:
1. **Re-authenticate**:
   ```bash
   agnt5 auth logout
   agnt5 auth login
   ```

2. **Generate new API key** from AGNT5 dashboard

3. **Update configuration**:
   ```bash
   agnt5 config set api-key your-new-key
   ```

## Deployment Issues

### Deployment Timeout

**Problem**: Deployments fail due to timeout.

**Solutions**:
1. **Increase timeout**:
   ```bash
   agnt5 deploy --timeout 600000  # 10 minutes
   ```

2. **Configure in project config**:
   ```javascript
   // agnt5.config.js
   module.exports = {
     deploy: {
       timeout: 600000
     }
   };
   ```

3. **Check deployment status**:
   ```bash
   agnt5 status --env production --verbose
   ```

4. **Use incremental deployment**:
   ```bash
   agnt5 deploy --incremental
   ```

### Build Failures

**Problem**: Build process fails during deployment.

**Solutions**:
1. **Check build logs**:
   ```bash
   agnt5 build --verbose
   ```

2. **Clean build cache**:
   ```bash
   agnt5 build --clean
   ```

3. **Test build locally**:
   ```bash
   agnt5 build --env production
   ```

4. **Check dependencies**:
   ```bash
   npm audit
   npm update
   ```

## Network Issues

### Connection Timeout

**Problem**: Commands fail with connection timeout.

**Solutions**:
1. **Check network connectivity**:
   ```bash
   ping api.agnt5.com
   ```

2. **Increase timeout**:
   ```bash
   agnt5 config set timeout 60000
   ```

3. **Configure proxy** (if behind corporate firewall):
   ```bash
   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080
   ```

4. **Use different base URL**:
   ```bash
   agnt5 config set base-url https://api-eu.agnt5.com
   ```

### SSL Certificate Issues

**Problem**: SSL/TLS certificate errors.

**Solutions**:
1. **Update Node.js** to latest stable version

2. **Use different registry** (temporary):
   ```bash
   npm config set registry https://registry.npmjs.org/
   ```

3. **Disable SSL verification** (not recommended for production):
   ```bash
   npm config set strict-ssl false
   ```

4. **Update CA certificates**:
   ```bash
   # macOS
   brew update && brew upgrade ca-certificates

   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get upgrade ca-certificates
   ```

## Performance Issues

### Slow Commands

**Problem**: CLI commands are running slowly.

**Solutions**:
1. **Enable caching**:
   ```bash
   agnt5 config set cache.enabled true
   ```

2. **Increase concurrency**:
   ```bash
   agnt5 config set concurrency 20
   ```

3. **Use local runtime** for development:
   ```bash
   agnt5 run workflow --local
   ```

4. **Profile command execution**:
   ```bash
   agnt5 --verbose --profile run workflow
   ```

### Memory Issues

**Problem**: CLI process uses too much memory.

**Solutions**:
1. **Increase Node.js memory limit**:
   ```bash
   export NODE_OPTIONS="--max-old-space-size=4096"
   agnt5 command
   ```

2. **Reduce concurrency**:
   ```bash
   agnt5 config set workflows.concurrency 5
   ```

3. **Clear cache**:
   ```bash
   agnt5 cache clear
   ```

## Configuration Issues

### Configuration Not Loading

**Problem**: CLI ignores configuration files.

**Solutions**:
1. **Verify config file location**:
   ```bash
   agnt5 config validate --verbose
   ```

2. **Check config file syntax**:
   ```bash
   node -c agnt5.config.js
   ```

3. **Use explicit config file**:
   ```bash
   agnt5 --config ./my-config.js command
   ```

4. **Reset configuration**:
   ```bash
   agnt5 config reset
   ```

## Getting Help

### Enable Debug Mode

For detailed troubleshooting information:

```bash
agnt5 --debug command
agnt5 --verbose command
```

### Check System Information

```bash
agnt5 doctor --verbose
```

### Validate Setup

```bash
agnt5 config validate
agnt5 auth whoami
agnt5 status --verbose
```

### Contact Support

If you're still experiencing issues:

1. **Check the logs**:
   ```bash
   agnt5 logs --level error --tail 100
   ```

2. **Create a minimal reproduction case**

3. **Include system information**:
   ```bash
   agnt5 --version
   node --version
   npm --version
   echo $AGNT5_API_KEY | cut -c1-8  # First 8 chars only
   ```

4. **Report the issue** with full error messages and steps to reproduce