Troubleshooting

Check logs:

docker compose logs backend
docker compose logs db

Common issues:

Symptom	Cause	Solution
`port is already allocated`	Port 5432, 8000, or 56421 in use	Stop conflicting service or change ports in `docker-compose.yaml`
`database not ready`	Database startup slow	Wait 30 seconds and check `docker compose ps` for "healthy" status
Backend crashloop	Missing dependencies	Run `docker compose up -d --build backend`

Check browser console (F12):

Error	Cause	Solution
`Failed to fetch` / CORS error	Backend not accessible or CORS misconfigured	Verify backend URL in `html/config.js` and CORS_ORIGINS in `docker-compose.yaml`
`404 Not Found` on template files	Nginx not serving files correctly	Check `docker compose logs frontend`
JavaScript errors	Broken code	Check `docker compose logs backend` for errors

Verify configuration:

# Check config.js loaded correctly
curl http://localhost:56421/config.js

# Test API directly
curl http://localhost:8000/api/health

Verify database is running:

docker compose ps db
docker exec inventory-db pg_isready -U inventory_user

Check credentials match:

# In docker-compose.yaml, verify these match:
# - db service: POSTGRES_USER / POSTGRES_PASSWORD
# - backend service: DATABASE_URL

Reset database connection:

docker compose restart backend

Reload schema manually:

docker exec -i inventory-db psql -U inventory_user -d inventory < db/schema.sql

⚠️ This destroys all data. For production, write migration scripts instead.

Verify trigger exists:

docker exec inventory-db psql -U inventory_user -d inventory -c "\df update_inventory_on_transfer_complete"

Check transfer status:

docker exec inventory-db psql -U inventory_user -d inventory -c "SELECT transfer_id, status FROM transfers ORDER BY created_at DESC LIMIT 5;"

Verify balances table:

docker exec inventory-db psql -U inventory_user -d inventory -c "SELECT * FROM inventory_balances LIMIT 10;"

If trigger is missing, reload schema (see above).