Troubleshooting Guide

Solutions to common issues in self-hosted ANTE ERP installations.

Quick Diagnosis

Start here to quickly identify the issue:

bash

# 1. Check all services are running
docker compose ps

# 2. Check logs for errors
docker compose logs --tail=50 backend

# 3. Check system resources
df -h && free -h

# 4. Test connectivity
curl http://localhost:8080
curl http://localhost:3001/health

Installation Issues

Issue: Docker compose command not found

Symptoms:

bash: docker: command not found

Solution:

bash

# Verify Docker is installed
docker --version

# If not installed, install Docker
# Ubuntu/Debian:
curl -fsSL https://get.docker.com | sh

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

Issue: Permission denied connecting to Docker

Symptoms:

permission denied while trying to connect to the Docker daemon socket

Solution:

bash

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

# Apply changes (logout and login, or run:)
newgrp docker

# Verify
docker ps

Issue: Port already in use

Symptoms:

Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use

Solution:

bash

# Find what's using the port
sudo lsof -i :8080
sudo netstat -tulpn | grep :8080

# Kill the process
sudo kill -9 <PID>

# Or change port in docker-compose.yml
ports:
  - "8081:80"  # Use different port

Issue: Cannot pull Docker images

Symptoms:

Error response from daemon: manifest unknown

Solution:

bash

# Check internet connectivity
ping -c 3 google.com

# Try pulling manually
docker pull ghcr.io/gtplusnet/ante-self-hosted-backend:latest

# If using proxy, configure Docker
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

# Add:
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:80"
Environment="HTTPS_PROXY=http://proxy.example.com:80"

# Restart Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

Container Issues

Issue: Container keeps restarting

Symptoms:

NAME            STATUS
ante-backend    Restarting (1) Less than a second ago

Diagnosis:

bash

# Check logs
docker compose logs backend

# Check exit code
docker inspect ante-backend | grep -A 5 "State"

# Check resource limits
docker stats ante-backend

Common Causes:

Database connection failed

bash

# Verify databases are healthy
docker compose ps postgres redis mongodb

# Check connection string in .env
cat .env | grep DATABASE_URL

Missing environment variables

bash

# Check required variables
docker compose exec backend printenv | grep -E "DATABASE|REDIS|JWT"

Out of memory

bash

# Check memory
docker stats

# Increase memory limits in docker-compose.yml:
deploy:
  resources:
    limits:
      memory: 2G

Issue: Container unhealthy

Symptoms:

NAME            STATUS
ante-backend    Up 5 minutes (unhealthy)

Solution:

bash

# Check health check logs
docker inspect ante-backend | grep -A 20 "Health"

# Test health endpoint
curl http://localhost:3001/health

# Restart container
docker compose restart backend

# If still unhealthy, rebuild
docker compose up -d --force-recreate backend

Database Issues

Issue: PostgreSQL connection refused

Symptoms:

FATAL: role "ante" does not exist
could not connect to server: Connection refused

Solutions:

Database not ready

bash

# Wait for database to be healthy
docker compose ps postgres

# Check logs
docker compose logs postgres

# Restart in order
docker compose stop backend
docker compose start postgres
sleep 10
docker compose start backend

Wrong credentials

bash

# Verify credentials in .env
cat .env | grep DB_PASSWORD

# Test connection
docker compose exec postgres psql -U ante -d ante_db -c "SELECT 1"

Database doesn't exist

bash

# Create database
docker compose exec postgres createdb -U ante ante_db

# Or connect and create manually
docker compose exec postgres psql -U postgres
postgres=# CREATE DATABASE ante_db OWNER ante;

Issue: PostgreSQL out of connections

Symptoms:

FATAL: sorry, too many clients already

Solution:

bash

# Check current connections
docker compose exec postgres psql -U ante -d ante_db -c \
  "SELECT count(*) FROM pg_stat_activity;"

# Kill idle connections
docker compose exec postgres psql -U ante -d ante_db -c \
  "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle';"

# Increase max_connections in docker-compose.yml
command:
  - postgres
  - -c
  - max_connections=200

# Restart
docker compose restart postgres

Issue: Redis connection failed

Symptoms:

Error: Redis connection to redis:6379 failed - NOAUTH Authentication required

Solution:

bash

# Verify password in .env
cat .env | grep REDIS_PASSWORD

# Test connection
docker compose exec redis redis-cli -a "$REDIS_PASSWORD" ping

# Should return: PONG

# If fails, restart Redis
docker compose restart redis

Issue: MongoDB authentication failed

Symptoms:

MongoServerError: Authentication failed

Solution:

bash

# Check credentials
cat .env | grep MONGO_PASSWORD

# Test connection
docker compose exec mongodb mongosh \
  --username ante \
  --password "$MONGO_PASSWORD" \
  --authenticationDatabase admin

# Reset password if needed
docker compose exec mongodb mongosh <<EOF
use admin
db.auth("admin", "admin")
db.changeUserPassword("ante", "new_password")
EOF

Application Issues

Issue: Backend API not responding

Symptoms:

Cannot reach http://localhost:3001
502 Bad Gateway errors
Timeout errors

Diagnosis:

bash

# 1. Check backend is running
docker compose ps backend

# 2. Check logs
docker compose logs --tail=100 backend

# 3. Check health endpoint
docker compose exec backend wget -O- http://localhost:3001/health

# 4. Check port binding
docker port ante-backend

Solutions:

Backend crashed

bash

docker compose restart backend
docker compose logs -f backend

Database migration needed

bash

docker compose exec backend npx prisma migrate deploy
docker compose restart backend

Environment variable issue

bash

# Verify all required vars are set
docker compose config | grep environment -A 20

Issue: Frontend shows blank page

Symptoms:

White screen
No content loads
Console shows errors

Solutions:

Check backend connection

bash

# Frontend needs backend to be running
curl http://localhost:3001/health

# If backend is down, start it
docker compose restart backend

Check browser console

Open browser DevTools (F12)
Look for errors in Console tab
Check Network tab for failed requests

Clear browser cache

bash

# Hard refresh
Ctrl+Shift+R (Linux/Windows)
Cmd+Shift+R (Mac)

Check frontend logs

bash

docker compose logs frontend

Symptoms:

"Invalid credentials" error
"JWT token invalid"
Session expires immediately

Solutions:

Check JWT secret

bash

# Ensure JWT_SECRET is set and consistent
cat .env | grep JWT_SECRET

# Restart backend if changed
docker compose restart backend

Clear Redis cache

bash

docker compose exec redis redis-cli -a "$REDIS_PASSWORD" FLUSHALL

Check database

bash

# Verify user exists
docker compose exec postgres psql -U ante -d ante_db -c \
  "SELECT username, email FROM users LIMIT 5;"

Reset user password

bash

# Through Prisma Studio
docker compose exec backend npx prisma studio

# Or SQL
docker compose exec postgres psql -U ante -d ante_db -c \
  "UPDATE users SET password = crypt('newpassword', gen_salt('bf')) WHERE username = 'admin';"

Issue: File upload fails

Symptoms:

Upload button not working
"File too large" error
Upload timeout

Solutions:

Check upload size limits

bash

# In .env
UPLOAD_MAX_SIZE=10485760  # 10MB

# In docker-compose.yml nginx section
client_max_body_size 100M;

Check disk space

bash

df -h
docker system df

Check volume permissions

bash

docker compose exec backend ls -la /app/uploads

Verify volume mount

bash

docker inspect ante-backend | grep -A 10 "Mounts"

Performance Issues

Issue: Slow response times

Diagnosis:

bash

# 1. Check system resources
docker stats

# 2. Check database performance
docker compose exec postgres psql -U ante -d ante_db -c \
  "SELECT query, calls, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"

# 3. Check Redis hit rate
docker compose exec redis redis-cli -a "$REDIS_PASSWORD" INFO stats | grep keyspace

Solutions:

Increase resources

yaml

# In docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

Enable Redis caching

bash

# In .env
CACHE_ENABLED=true
CACHE_TYPE=redis
CACHE_DEFAULT_TTL=3600

Optimize database

bash

# Run vacuum and analyze
docker compose exec postgres psql -U ante -d ante_db -c "VACUUM ANALYZE;"

# Add indexes for slow queries

Check network latency

bash

# Between containers
docker compose exec backend ping -c 3 postgres

Issue: High memory usage

Symptoms:

Out of memory
Container killed (OOMKilled)
System slow

Solutions:

Identify memory hog

bash

docker stats --no-stream

Increase swap

bash

# Create swap file
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Set memory limits

yaml

services:
  backend:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

Clean up

bash

docker system prune -a
docker volume prune

Issue: Database disk space full

Symptoms:

ERROR: could not extend file: No space left on device

Solutions:

Check space usage

bash

docker system df -v
du -sh ~/ante-erp/*

Clean up old data

bash

# Vacuum database
docker compose exec postgres psql -U ante -d ante_db -c "VACUUM FULL;"

# Remove old logs
find ~/ante-erp/logs -name "*.log" -mtime +30 -delete

# Clean Docker
docker system prune -a --volumes

Move volumes to larger disk

bash

# Stop services
docker compose down

# Move data
sudo mv /var/lib/docker/volumes ~/new-location/

# Create symlink
sudo ln -s ~/new-location/volumes /var/lib/docker/volumes

# Start services
docker compose up -d

Network Issues

Issue: Cannot access from other computers

Symptoms:

Works on localhost
Cannot access from network
Connection refused

Solutions:

Check firewall

bash

# UFW (Ubuntu)
sudo ufw status
sudo ufw allow 8080/tcp
sudo ufw allow 3001/tcp

# Firewalld (CentOS)
sudo firewall-cmd --list-all
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

Check port binding

bash

# Should bind to 0.0.0.0, not 127.0.0.1
docker compose ps
netstat -tuln | grep 8080

Test from remote machine

bash

# From another computer
telnet YOUR_SERVER_IP 8080
curl http://YOUR_SERVER_IP:8080

Issue: WebSocket connection fails

Symptoms:

Real-time updates not working
"WebSocket connection failed" in console

Solutions:

Check WebSocket port

bash

curl -I http://localhost:4001

Configure reverse proxy for WebSocket

nginx

location /socket.io/ {
    proxy_pass http://localhost:4001/socket.io/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Check firewall allows WebSocket port

bash

sudo ufw allow 4001/tcp

SSL/HTTPS Issues

Issue: SSL certificate errors

Symptoms:

"Your connection is not private"
Certificate expired
Certificate invalid

Solutions:

Renew certificate

bash

sudo certbot renew
sudo systemctl reload nginx

Check certificate status

bash

sudo certbot certificates

Force renewal

bash

sudo certbot renew --force-renewal

Issue: Mixed content warnings

Symptoms:

Some resources blocked
"Mixed content" in console

Solution: Update all URLs to use HTTPS:

bash

# In .env
FRONTEND_URL=https://erp.yourcompany.com
API_URL=https://erp.yourcompany.com/api
SOCKET_URL=wss://erp.yourcompany.com/socket.io

Recovery Procedures

Complete System Recovery

If everything is broken:

bash

# 1. Stop everything
cd ~/ante-erp
docker compose down

# 2. Backup current state
sudo tar -czf ~/ante-erp-emergency-backup.tar.gz ~/ante-erp

# 3. Clean Docker
docker system prune -a --volumes

# 4. Restore from backup
./scripts/restore-backup.sh ~/ante-erp/backups/ante-erp-backup-LATEST.tar.gz

# 5. Start fresh
docker compose pull
docker compose up -d

# 6. Verify
docker compose ps
curl http://localhost:8080

Reset Database

⚠️ WARNING: This deletes all data!

bash

# Stop backend
docker compose stop backend

# Drop and recreate database
docker compose exec postgres psql -U postgres -c "DROP DATABASE ante_db;"
docker compose exec postgres psql -U postgres -c "CREATE DATABASE ante_db OWNER ante;"

# Run migrations
docker compose start backend
docker compose exec backend npx prisma migrate deploy

# Restart
docker compose restart backend

Getting Help

If you can't resolve the issue:

Collect diagnostic information:

bash

# Save all information
./scripts/health-check.sh > diagnostic_$(date +%Y%m%d).txt
docker compose logs > logs_$(date +%Y%m%d).txt
docker compose config > config_$(date +%Y%m%d).txt

Check documentation:

Contact support:

Email: support@ante.ph
Include diagnostic files
Describe steps to reproduce

Common Error Messages

Error	Likely Cause	Solution
`ECONNREFUSED`	Service not running	Start the service
`ENOTFOUND`	DNS/hostname issue	Check container names
`ETIMEDOUT`	Network/firewall	Check firewall rules
`EACCES`	Permission denied	Check file/directory permissions
`ENOSPC`	Disk full	Free up space
`OOMKilled`	Out of memory	Increase RAM or add swap
`unhealthy`	Health check failing	Check logs, restart service

Prevention

Prevent future issues:

Regular backups - Daily automated backups
Monitoring - Set up health checks
Updates - Keep system updated
Documentation - Document custom changes
Testing - Test backups regularly

Last Updated: October 27, 2025

Troubleshooting Guide ​

Quick Diagnosis ​

Installation Issues ​

Issue: Docker compose command not found ​

Issue: Permission denied connecting to Docker ​

​

Issue: Cannot pull Docker images ​

Container Issues ​

Issue: Container keeps restarting ​

Issue: Container unhealthy ​

Database Issues ​

Issue: PostgreSQL connection refused ​

Issue: PostgreSQL out of connections ​

Issue: Redis connection failed ​

Issue: MongoDB authentication failed ​

Application Issues ​

Issue: Backend API not responding ​

Issue: Frontend shows blank page ​

Issue: Cannot login / Authentication errors ​

Issue: File upload fails ​

Performance Issues ​

Issue: Slow response times ​

Issue: High memory usage ​

Issue: Database disk space full ​

Network Issues ​

Issue: Cannot access from other computers ​

Issue: WebSocket connection fails ​

SSL/HTTPS Issues ​

Issue: SSL certificate errors ​

Issue: Mixed content warnings ​

Recovery Procedures ​

Complete System Recovery ​

Reset Database ​

Getting Help ​

Common Error Messages ​

Prevention ​

Troubleshooting Guide

Quick Diagnosis

Installation Issues

Issue: Docker compose command not found

Issue: Permission denied connecting to Docker

Issue: Cannot pull Docker images

Container Issues

Issue: Container keeps restarting

Issue: Container unhealthy

Database Issues

Issue: PostgreSQL connection refused

Issue: PostgreSQL out of connections

Issue: Redis connection failed

Issue: MongoDB authentication failed

Application Issues

Issue: Backend API not responding

Issue: Frontend shows blank page

Issue: Cannot login / Authentication errors

Issue: File upload fails

Performance Issues

Issue: Slow response times

Issue: High memory usage

Issue: Database disk space full

Network Issues

Issue: Cannot access from other computers

Issue: WebSocket connection fails

SSL/HTTPS Issues

Issue: SSL certificate errors

Issue: Mixed content warnings

Recovery Procedures

Complete System Recovery

Reset Database

Getting Help

Common Error Messages

Prevention