Troubleshooting

A service won't become healthy

docker compose ps
docker compose logs --tail=80 backend

/health returns 200 but no data comes through

The backend starts up even if MongoDB is unreachable (by design) and retries on the first query. Check MONGODB_URI and MongoDB access. Seeing getaddrinfo ENOTFOUND on data endpoints means the address is wrong.

Port already in use

Change FRONTEND_PORT in .env and run ./update.sh --no-pull.

Update says "there are uncommitted changes"

This is a safety guard — it stops so your changes aren't overwritten. Run git stash, git commit, or use ./update.sh --no-pull to reinstall without pulling.

Script doesn't run on Windows

powershell -ExecutionPolicy Bypass -File .\install.ps1

Native mode and uninstall operations require administrator rights.

Docker Desktop isn't ready

The script waits for it to start. If it takes too long, start Docker Desktop manually and retry.

npm test hangs / times out in CI

Backend tests never open a real connection to MongoDB — test/env.setup.mjs assigns harmless defaults to the required environment variables (MONGODB_URI, ERP_AUTH_SECRET, GO_API_BASE_URL) just to pass readRequired validation. If tests hang locally, first make sure your backend/.env file isn't affecting the test run.

k6 smoke test won't run against production

This is a deliberate safety gate (assertNonProductionTarget). k6 tests can only target localhost / *.test / *.local / *staging* / *.internal addresses.