Troubleshooting

Troubleshooting

Problems seen when running the app and tests locally, especially on Windows, and how to fix them. For normal setup, see Getting Started.

Running the app

The page at 127.0.0.1:5173 doesn't load

The Vite dev server listens on localhost only (IPv6 ::1 on Windows), so http://127.0.0.1:5173 doesn't connect. Open http://localhost:5173.

password authentication failed for user "seating"

Another PostgreSQL is already on port 5432, for example a local Windows PostgreSQL service, and the backend connected to it instead of the Compose database. Docker can bind 5432 at the same time, so docker compose up still looks healthy.

Check what's listening:

netstat -ano | findstr ":5432"
tasklist | findstr postgres

Then either:

• Run Compose on another port:

  $env:POSTGRES_PORT = "5433"; docker compose up -d --wait
  $env:DB_URL = "jdbc:postgresql://localhost:5433/seating"; .\mvnw.cmd spring-boot:run

• Skip Compose: run .\mvnw.cmd spring-boot:test-run in backend/. It uses its own throwaway Testcontainers PostgreSQL, and its data is lost when it stops.

Ports 8080 or 5173 are still in use after stopping the servers

Stopping the terminal or shell that launched a server can leave the Java or Node process running. Find the process and stop it:

netstat -ano | findstr ":8080 :5173"
Stop-Process -Id <PID>

When the backend stops, Testcontainers removes its database container automatically.

The backend takes minutes to start

spring-boot:test-run starts a PostgreSQL container first. On a slow machine or a small Docker VM, this can take several minutes (7 minutes was seen on a 4 GB laptop). The Testcontainers startup timeout is 4 minutes. Wait for Started SeatingApplication in the log.

"Reconnecting… the map may be out of date" never goes away

The WebSocket can't reach the backend. Check that the backend is running on port 8080 and that you opened the app through the Vite dev server (localhost:5173), which proxies /ws.

Desks for "today" look wrong around midnight

The date picker uses the browser's time zone, but the backend decides "today" with BOOKING_ZONE (default UTC). Set BOOKING_ZONE to your office's zone if they differ. The end-to-end tests pass the same zone to both sides through E2E_TIME_ZONE.

Low memory

On a machine with about 4 GB of RAM, running Docker, the backend, the frontend, and Playwright's browsers together can exhaust memory. Symptoms:

• The backend log shows HikariPool-1 - Failed to validate connection ... (This connection has been closed.) many times, or Thread starvation or clock leap detected.
• The app hangs on "Signing in…" or "Loading the floor map…", even though the connection indicator says Live.
• End-to-end tests time out at sign-in or during races, with no wrong states in the screenshots.
• Claude Code stops background servers with "the system is running low on memory".
• A JVM crashes during ./mvnw verify.

These are environment problems, not app bugs. To fix them:

• Close other apps before running the stack.
• Give Docker Desktop more memory (Settings → Resources).
• Run one end-to-end file at a time, for example npx playwright test tests/race.spec.ts.
• Rely on CI for the full suite, which passes 10/10 in about 1.5 minutes.

Builds and tests

Premature end of Content-Length delimited message body from Maven

A dependency download was cut off by the network. Rerun the same command; Maven resumes where it stopped.

'mvnw.cmd' is not recognized or ./mvnw: Permission denied

• On Windows, run the wrapper with a path: .\mvnw.cmd. Tools that start it through cmd, like Playwright's webServer, need .\\mvnw.cmd in a JavaScript string.
• On macOS, Linux, and CI, backend/mvnw must be executable and use LF line endings. The repo's .gitattributes keeps it LF, and git stores it as executable (100755). If you recreate it on Windows, run git update-index --chmod=+x backend/mvnw.

The first Vitest run on Windows times out

Starting jsdom for the first time can take over a minute. Rerun npm test. On a slow machine, run one file at a time with npx vitest run <file>, or add --no-file-parallelism.

Playwright can't find a browser

Install Chromium from e2e/ with npm run install:browsers. To keep the browser inside the repo instead of your user cache, set PLAYWRIGHT_BROWSERS_PATH for both the install and the test run:

$env:PLAYWRIGHT_BROWSERS_PATH = "$PWD\.playwright-browsers"
npm run install:browsers
npm test

End-to-end tests changed my local bookings

The tests reuse a running backend when one is available. Before and after each test, they cancel every seeded user's bookings on the test's date (today + 2 through today + 10). Don't rely on bookings in those dates while running the suite, or run it against a separate backend.

GitHub workflow

An issue stayed open after its PR was squash-merged

Squash merges don't always close the linked issue. Check with gh issue view <n>, and if it's still open, close it with a link to the PR: gh issue close <n> --comment "Done in #<pr>.".

gh pr merge fails to delete the local branch

This happens when you work in a git worktree and main is checked out in another one. The PR is still merged and the remote branch deleted. Confirm with gh pr view <pr> --json state, then delete the local branch yourself.