CLI Troubleshooting Guide

Solutions to common issues when using the ANTE CLI.

Diagnostic Tools

Before troubleshooting specific issues, run these diagnostic commands:

bash

# Check system health
ante doctor

# Check service status
ante status

# View recent logs
ante logs --lines 200

# Check CLI version
ante --version

Installation Issues

Command Not Found

Symptom:

bash

$ ante --version
bash: ante: command not found

Cause: CLI not installed or not in PATH.

Solution:

Verify installation:

bash

npm list -g ante-erp-cli

If not installed, install it:

bash

npm install -g ante-erp-cli

If installed but not found, add npm global bin to PATH:

bash

# Find npm global bin directory
npm config get prefix

# Add to PATH (Linux/macOS)
export PATH="$(npm config get prefix)/bin:$PATH"

# Make permanent
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

npm Permission Errors

Symptom:

bash

npm ERR! Error: EACCES: permission denied

Cause: Insufficient permissions to install global npm packages.

Solution 1 (Recommended): Configure npm to use a user directory:

bash

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Install again
npm install -g ante-erp-cli

Solution 2 (Not Recommended): Use sudo:

bash

sudo npm install -g ante-erp-cli

Solution 3: Use npx instead:

bash

npx ante-erp-cli install

Node.js Version Too Old

Symptom:

bash

error This version of ANTE requires Node.js 24.0.0 or higher

Cause: Node.js version is below 24.0.0.

Solution:

Check current version:

bash

node --version

Update Node.js (Ubuntu/Debian):

bash

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

Update Node.js (macOS with Homebrew):

bash

brew update
brew upgrade node

Verify:

bash

node --version  # Should be 24.0.0 or higher

Docker Issues

Docker Daemon Not Running

Symptom:

bash

Error: Cannot connect to the Docker daemon

Cause: Docker service is not running.

Solution:

bash

# Check Docker status
sudo systemctl status docker

# Start Docker
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker

# Verify
docker ps

Docker Permission Denied

Symptom:

bash

permission denied while trying to connect to the Docker daemon socket

Cause: Current user doesn't have permission to access Docker.

Solution:

bash

# Add user to docker group
sudo usermod -aG docker $USER

# Apply group changes
newgrp docker

# Or log out and log back in

# Verify
docker ps

Docker Compose Version Mismatch

Symptom:

bash

Error: Docker Compose v2 required, found v1

Cause: Old Docker Compose version installed.

Solution:

bash

# Remove old Docker Compose
sudo apt-get remove docker-compose

# Install Docker Compose v2 (comes with Docker Desktop)
# Or install plugin:
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Verify
docker compose version  # Should be 2.x.x

Installation Detection Issues

Installation Not Found

Symptom:

bash

Error: ANTE installation not found

Cause: CLI can't find the ANTE installation directory.

Solution:

Check if installation exists:

bash

ls -la ./ante-erp

If it exists, navigate to the directory:

bash

cd /path/to/ante-erp
ante status

If installation doesn't exist, install ANTE:

bash

ante install

Check CLI configuration:

bash

cat ~/.config/ante-cli/config.json

Multiple Installations Detected

Symptom: CLI is confused about which installation to use.

Solution:

Navigate to the installation directory you want to use:

bash

cd /path/to/ante-erp

Run commands from that directory:

bash

ante status

Or update CLI configuration manually:

bash

nano ~/.config/ante-cli/config.json
# Edit "installPath" to point to correct directory

Service Issues

Services Won't Start

Symptom:

bash

$ ante start
Error: Failed to start services

Diagnostics:

bash

# Check what's wrong
ante doctor

# Check Docker logs
ante logs --lines 500

# Check specific service
ante logs --service backend --follow

Common Causes & Solutions:

Port Already in Use

bash

# Find what's using the port
sudo lsof -i :8080

# Kill the process
sudo kill -9 <PID>

# Or change ANTE's port
nano ./ante-erp/.env
# Change FRONTEND_PORT=9000
ante restart

Out of Disk Space

bash

# Check disk space
df -h

# Clean up Docker
docker system prune -a --volumes

# Remove old images
docker images
docker rmi <image-id>

Out of Memory

bash

# Check memory
free -h

# Increase Docker memory limit (Docker Desktop)
# Settings → Resources → Memory → Increase

# Or restart services one by one
ante stop
ante start --service postgres
ante start --service redis
ante start --service mongodb
ante start --service backend
ante start --service frontend

Services Keep Restarting

Symptom: Services show as "restarting" instead of "running".

Diagnostics:

bash

# Watch logs in real-time
ante logs --service backend --follow

# Check Docker events
docker events

# Check resource usage
docker stats

Common Causes:

Configuration Error: Check .env file for typos
Database Connection: Ensure database is running first
Insufficient Memory: Increase available RAM
Corrupt Image: Pull fresh images

Solution:

bash

# Stop everything
ante stop

# Remove containers
docker compose -f ./ante-erp/docker-compose.yml down

# Pull fresh images
docker compose -f ./ante-erp/docker-compose.yml pull

# Start again
ante start

Database Connection Errors

Symptom:

bash

Error: Unable to connect to database

Diagnostics:

bash

# Check if PostgreSQL is running
ante status

# Check database logs
ante logs --service postgres

# Try connecting manually
ante db shell

Solutions:

Restart database:

bash

ante restart --service postgres

Check credentials:

bash

cat ./ante-erp/.env | grep DATABASE
# Verify DATABASE_URL is correct

Reset database (⚠️ destructive):

bash

ante backup  # Backup first!
ante db reset

Backup & Restore Issues

Backup Fails

Symptom:

bash

Error: Backup creation failed

Common Causes & Solutions:

Insufficient Disk Space

bash

# Check available space
df -h ./backups

# Clean up old backups
rm ./backups/ante-backup-old*.tar.gz

Permission Denied

bash

# Fix permissions
sudo chown -R $USER:$USER ./backups
chmod -R 755 ./backups

Services Not Running

bash

# Start services first
ante start

# Then create backup
ante backup

Restore Fails

Symptom:

bash

Error: Restore operation failed

Solution:

bash

# Stop all services
ante stop

# Manually remove containers and volumes
docker compose -f ./ante-erp/docker-compose.yml down -v

# Try restore again
ante restore ./backups/your-backup.tar.gz

# If still fails, restore manually:
# 1. Extract backup
tar -xzf ./backups/your-backup.tar.gz -C ./temp-restore

# 2. Start services
ante start

# 3. Restore database manually
cat ./temp-restore/postgres.dump | docker exec -i ante-postgres psql -U ante -d ante_db

Update Issues

Update Fails

Symptom:

bash

Error: Update failed

Solution:

Create manual backup first:

bash

ante backup

Check current version:

bash

docker images | grep ante

Force pull new images:

bash

docker compose -f ./ante-erp/docker-compose.yml pull

Run update again:

bash

ante update

If still fails, restore from backup:

bash

ante restore

Update Succeeds But Services Don't Start

Solution:

bash

# Check logs for errors
ante logs

# Run database migrations manually
docker compose -f ./ante-erp/docker-compose.yml exec backend npm run migration:run

# Restart services
ante restart

Performance Issues

Slow Performance

Diagnostics:

bash

# Check resource usage
docker stats

# Check database performance
ante db info

# Check logs for slow queries
ante logs --service backend | grep "slow query"

Solutions:

Optimize database:

bash

ante db optimize

Increase Docker resources:
- Docker Desktop: Settings → Resources → Increase CPU/Memory
- Linux: Edit /etc/docker/daemon.json
Clean up old data:

bash

# Docker cleanup
docker system prune -a

# Database cleanup (be careful!)
ante db optimize

High Memory Usage

Symptom: System runs out of memory.

Solution:

bash

# Check what's using memory
docker stats

# Restart services to clear memory leaks
ante restart

# Reduce Docker memory limits
nano ./ante-erp/docker-compose.yml
# Add memory limits to services:
# services:
#   backend:
#     mem_limit: 2g

Network Issues

Can't Access Frontend

Symptom: Browser can't connect to http://localhost:8080

Diagnostics:

bash

# Check if frontend is running
ante status

# Check port binding
sudo lsof -i :8080

# Check firewall
sudo ufw status

Solutions:

Port is already in use:

bash

# Kill process using port
sudo lsof -i :8080
sudo kill -9 <PID>

# Or change ANTE port
nano ./ante-erp/.env
# FRONTEND_PORT=9000
ante restart

Firewall blocking:

bash

# Allow port through firewall
sudo ufw allow 8080

Wrong URL:
- Use http:// not https:// (unless SSL is configured)
- Use localhost not 127.0.0.1 in some cases

SSL Certificate Issues

Symptom: Certificate errors when accessing via HTTPS.

Solution:

bash

# Check certificate status
sudo certbot certificates

# Renew certificate
sudo certbot renew

# Or use CLI
ante ssl:renew  # If this command exists

Data Issues

Data Loss After Restart

Symptom: Data disappears after restarting services.

Cause: Docker volumes not configured correctly.

Prevention:

bash

# Always use named volumes (not bind mounts)
docker volume ls

# Backup regularly
ante backup  # Set up in cron

Recovery:

bash

# Restore from latest backup
ante backup list
ante restore ./backups/ante-backup-latest.tar.gz

Corrupted Database

Symptom: Database errors, can't query data.

Solution:

bash

# 1. Create backup of corrupted DB (if possible)
ante backup --databases-only

# 2. Try database repair
docker compose -f ./ante-erp/docker-compose.yml exec postgres vacuumdb -U ante -d ante_db --full --analyze

# 3. If that fails, restore from backup
ante restore ./backups/ante-backup-yesterday.tar.gz

# 4. Last resort: Reset database
ante db reset  # ⚠️ Deletes all data!

CLI-Specific Issues

CLI Configuration Corrupted

Symptom: CLI behaves unexpectedly.

Solution:

bash

# Remove CLI config
rm -rf ~/.config/ante-cli

# Re-run commands from installation directory
cd /path/to/ante-erp
ante status  # This will recreate config

"ANTE not installed" But It Is

Solution:

bash

# Navigate to installation directory
cd /path/to/ante-erp

# Run commands from there
ante status

# Or manually set in config
echo '{"installPath": "/path/to/ante-erp"}' > ~/.config/ante-cli/config.json

Getting More Help

Enable Debug Mode

Some issues require verbose logging:

bash

# Set environment variable for detailed logs
export DEBUG=ante:*

# Run command
ante start

# Or with single command
DEBUG=ante:* ante doctor

Collect Diagnostic Information

When reporting issues, collect this information:

bash

# System information
uname -a
docker --version
docker compose version
node --version
ante --version

# Service status
ante status

# Recent logs
ante logs --lines 500 > ante-debug-logs.txt

# Docker information
docker ps -a
docker images
docker volume ls

Report an Issue

If you're still stuck:

Search existing issues: GitHub Issues
Create new issue with:
- Symptom description
- Steps to reproduce
- Diagnostic information (above)
- Error messages
- Screenshots (if applicable)
Contact support:
- Email: support@ante.ph
- Include diagnostic information

Common Error Messages

"Port already in use"

Fix: Change port or kill process using it:

bash

sudo lsof -i :8080
sudo kill -9 <PID>

"Cannot connect to Docker daemon"

Fix: Start Docker service:

bash

sudo systemctl start docker

"Database connection refused"

Fix: Ensure PostgreSQL is running:

bash

ante restart --service postgres

"Insufficient memory"

Fix: Increase Docker memory or free up RAM:

bash

docker system prune -a

"Permission denied"

Fix: Check file/Docker permissions:

bash

sudo usermod -aG docker $USER
newgrp docker

Prevention Tips

Regular Maintenance

bash

# Weekly backup
ante backup

# Monthly optimization
ante db optimize

# Periodic updates
ante update

Monitoring Script

Create a cron job to monitor ANTE health:

bash

# health-monitor.sh
#!/bin/bash
if ! ante status > /dev/null 2>&1; then
    echo "ANTE is down! Attempting restart..."
    ante restart
    # Send notification
fi

bash

# Add to crontab
crontab -e
# Run every 5 minutes
*/5 * * * * /path/to/health-monitor.sh

Next Steps

CLI Reference - Complete command reference
Installation Guide - Install or reinstall CLI
Self-Hosting Guide - General troubleshooting

Still having issues? Contact support or open an issue on GitHub.

CLI Troubleshooting Guide ​

Diagnostic Tools ​

Installation Issues ​

Command Not Found ​

npm Permission Errors ​

Node.js Version Too Old ​

Docker Issues ​

Docker Daemon Not Running ​

Docker Permission Denied ​

Docker Compose Version Mismatch ​

Installation Detection Issues ​

Installation Not Found ​

Multiple Installations Detected ​

Service Issues ​

Services Won't Start ​

Port Already in Use ​

Out of Disk Space ​

Out of Memory ​

Services Keep Restarting ​

Database Connection Errors ​

Backup & Restore Issues ​

Backup Fails ​

Insufficient Disk Space ​

Permission Denied ​

Services Not Running ​

Restore Fails ​

Update Issues ​

Update Fails ​

Update Succeeds But Services Don't Start ​

Performance Issues ​

Slow Performance ​

High Memory Usage ​

Network Issues ​

Can't Access Frontend ​

SSL Certificate Issues ​

Data Issues ​

Data Loss After Restart ​

Corrupted Database ​

CLI-Specific Issues ​

CLI Configuration Corrupted ​

"ANTE not installed" But It Is ​

Getting More Help ​

Enable Debug Mode ​

Collect Diagnostic Information ​

Report an Issue ​

Common Error Messages ​

"Port already in use" ​

"Cannot connect to Docker daemon" ​

"Database connection refused" ​

"Insufficient memory" ​

"Permission denied" ​

Prevention Tips ​

Regular Maintenance ​

Monitoring Script ​

Next Steps ​

CLI Troubleshooting Guide

Diagnostic Tools

Installation Issues

Command Not Found

npm Permission Errors

Node.js Version Too Old

Docker Issues

Docker Daemon Not Running

Docker Permission Denied

Docker Compose Version Mismatch

Installation Detection Issues

Installation Not Found

Multiple Installations Detected

Service Issues

Services Won't Start

Port Already in Use

Out of Disk Space

Out of Memory

Services Keep Restarting

Database Connection Errors

Backup & Restore Issues

Backup Fails

Insufficient Disk Space

Permission Denied

Services Not Running

Restore Fails

Update Issues

Update Fails

Update Succeeds But Services Don't Start

Performance Issues

Slow Performance

High Memory Usage

Network Issues

Can't Access Frontend

SSL Certificate Issues

Data Issues

Data Loss After Restart

Corrupted Database

CLI-Specific Issues

CLI Configuration Corrupted

"ANTE not installed" But It Is

Getting More Help

Enable Debug Mode

Collect Diagnostic Information

Report an Issue

Common Error Messages

"Port already in use"

"Cannot connect to Docker daemon"

"Database connection refused"

"Insufficient memory"

"Permission denied"

Prevention Tips

Regular Maintenance

Monitoring Script

Next Steps