Troubleshooting

Connection Refused from Browser

Symptom: Browser can't reach http://{IP}:6080

# Check containers are running
docker ps

# Open firewall ports
sudo ufw allow 6080/tcp
sudo ufw allow 6081/tcp

If using a cloud server, also check the cloud provider's security group/firewall rules.

Container Won't Start / Build Fails

Most common cause: Missing GITHUB_TOKEN

grep GITHUB_TOKEN .env.testip.local
# Should show: GITHUB_TOKEN=ghp_... (not empty)

Rebuild from scratch:

docker compose -f docker-compose.ip-test.yml down -v
docker compose -f docker-compose.ip-test.yml --env-file .env.testip.local up -d --build

Database Errors

Symptom: SQLSTATE[08006] or migration failures

# Check postgres is healthy
docker inspect ubios_postgres --format='{{.State.Health.Status}}'
# Should show: healthy

# If not healthy, check logs
docker compose -f docker-compose.ip-test.yml logs postgres

# Test connection
docker exec -it ubios_api bash -c '
  PGPASSWORD=331331331 psql -U postgres -h ubios_postgres -d ubios -c "SELECT 1;"
'

# If connection works but migration fails, check schema exists
docker exec -it ubios_api bash -c '
  PGPASSWORD=331331331 psql -U postgres -h ubios_postgres -d ubios -c "\dn"
'

Port Already in Use

Symptom: bind: address already in use

# Find what's using the port
sudo lsof -i :5432    # PostgreSQL
sudo lsof -i :6080    # Nuxt
sudo lsof -i :6379    # Redis
sudo lsof -i :8001    # Agno

# Kill the conflicting process or change the port in docker-compose

Agno Returns Errors

Symptom: Agent queries fail or return LLM errors

# Check Agno health (includes LLM provider status)
curl http://$HOST_IP:8001/health

# Check Agno logs
docker compose -f docker-compose.ip-test.yml logs --tail=50 agno

Common Agno issues:

LLM_FAILURE: API key missing or invalid. Check the key for the provider in .env.testip.local.
SCHEMA_NOT_FOUND: Migrations haven't run. Run docker exec -it ubios_api php artisan migrate.
AGENT_TIMEOUT: LLM provider is slow or rate-limited. Try again or switch to a faster model.

Queue Jobs Not Processing

Symptom: Scheduled agents don't run, document extraction hangs

# Check queue worker is running
docker compose -f docker-compose.ip-test.yml logs --tail=20 queue

# Check for failed jobs
docker exec -it ubios_api php artisan queue:failed

# Restart the queue worker
docker compose -f docker-compose.ip-test.yml restart queue

Nuxt Shows Blank Page

Symptom: Frontend loads but shows nothing

# Check Nuxt is serving
docker compose -f docker-compose.ip-test.yml logs --tail=20 app

# Common issue: API proxy not connecting
# Verify NUXT_API_PROXY_TARGET points to correct container
docker exec -it ubios_app sh -c 'echo $NUXT_API_PROXY_TARGET'
# Should show: http://ubios_api:8000

MinIO / Document Upload Fails

# Check MinIO is healthy
curl -sf http://$HOST_IP:9000/minio/health/live

# Check MinIO credentials
docker exec -it ubios_api bash -c 'echo $MINIO_ACCESS_KEY'

Reset Everything

# Nuclear option: stop, delete all data and images, start fresh
docker compose -f docker-compose.ip-test.yml down -v --rmi local
docker compose -f docker-compose.ip-test.yml --env-file .env.testip.local up -d --build

# Then re-initialize
docker exec -it ubios_api bash -c '
  PGPASSWORD=331331331 psql -U postgres -h ubios_postgres -c "CREATE DATABASE ubios_dify;" 2>/dev/null
  PGPASSWORD=331331331 psql -U postgres -h ubios_postgres -c "CREATE DATABASE ubios_metabase;" 2>/dev/null
'
docker exec -it ubios_api php artisan key:generate --force
docker exec -it ubios_api php artisan migrate
docker exec -it ubios_api php artisan db:seed --class=UbiosDatabaseSeeder