Docs
⌘ K
API Reference Troubleshooting — AGNT5 CLI

Troubleshooting

Common issues and solutions for the AGNT5 CLI

Common issues and solutions when using the AGNT5 CLI.

Installation Issues

Command Not Found

Problem: agnt5: command not found after installation.

Solutions:

  1. Check if npm global packages are in PATH:

    npm config get prefix
echo $PATH

  2. Reinstall the CLI:

    npm uninstall -g agnt5
npm install -g agnt5

  3. Use npx as alternative:

    npx agnt5 --version

  4. Add npm global bin to PATH (if missing):

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

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

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

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

    wsl --install
# Then install in WSL environment

  3. Use Chocolatey:

    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:

    agnt5 config get api-key

  2. Reset and re-enter API key:

    agnt5 config set api-key your-new-api-key

  3. Use interactive login:

    agnt5 auth login

  4. Check environment variables:

    echo $AGNT5_API_KEY

Token Expired

Problem: Authentication token has expired.

Solutions:

  1. Re-authenticate:

    agnt5 auth logout
agnt5 auth login

  2. Generate new API key from AGNT5 dashboard

  3. Update configuration:

    agnt5 config set api-key your-new-key

Deployment Issues

Deployment Timeout

Problem: Deployments fail due to timeout.

Solutions:

  1. Increase timeout:

    agnt5 deploy --timeout 600000  # 10 minutes

  2. Configure in project config:

    // agnt5.config.js
module.exports = {
  deploy: {
    timeout: 600000
  }
};

  3. Check deployment status:

    agnt5 status --env production --verbose

  4. Use incremental deployment:

    agnt5 deploy --incremental

Build Failures

Problem: Build process fails during deployment.

Solutions:

  1. Check build logs:

    agnt5 build --verbose

  2. Clean build cache:

    agnt5 build --clean

  3. Test build locally:

    agnt5 build --env production

  4. Check dependencies:

    npm audit
npm update

Network Issues

Connection Timeout

Problem: Commands fail with connection timeout.

Solutions:

  1. Check network connectivity:

    ping api.agnt5.com

  2. Increase timeout:

    agnt5 config set timeout 60000

  3. Configure proxy (if behind corporate firewall):

    npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

  4. Use different base URL:

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

    npm config set registry https://registry.npmjs.org/

  3. Disable SSL verification (not recommended for production):

    npm config set strict-ssl false

  4. Update CA certificates:

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

    agnt5 config set cache.enabled true

  2. Increase concurrency:

    agnt5 config set concurrency 20

  3. Use local runtime for development:

    agnt5 run workflow --local

  4. Profile command execution:

    agnt5 --verbose --profile run workflow

Memory Issues

Problem: CLI process uses too much memory.

Solutions:

  1. Increase Node.js memory limit:

    export NODE_OPTIONS="--max-old-space-size=4096"
agnt5 command

  2. Reduce concurrency:

    agnt5 config set workflows.concurrency 5

  3. Clear cache:

    agnt5 cache clear

Configuration Issues

Configuration Not Loading

Problem: CLI ignores configuration files.

Solutions:

  1. Verify config file location:

    agnt5 config validate --verbose

  2. Check config file syntax:

    node -c agnt5.config.js

  3. Use explicit config file:

    agnt5 --config ./my-config.js command

  4. Reset configuration:

    agnt5 config reset

Getting Help

Enable Debug Mode

For detailed troubleshooting information:

agnt5 --debug command
agnt5 --verbose command

Check System Information 

agnt5 doctor --verbose

Validate Setup 

agnt5 config validate
agnt5 auth whoami
agnt5 status --verbose

Contact Support

If you’re still experiencing issues:

  1. Check the logs:

    agnt5 logs --level error --tail 100

  2. Create a minimal reproduction case

  3. Include system information:

    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

© 2026 AGNT5
llms.txt