Java "Address already in use" / Port In Use - Fix in CI

A Java process tried to bind a TCP port that was already taken. In CI this is usually an integration test starting an embedded server on a fixed port while a previous instance (or a parallel job) still holds it.

What this error means

The test or boot fails with java.net.BindException: Address already in use on a fixed port like 8080. It can be intermittent -- it depends on whether a prior process released the port -- so a re-run sometimes passes.

Caused by: java.net.BindException: Address already in use
	at java.base/sun.nio.ch.Net.bind0(Native Method)
	... Web server failed to start. Port 8080 was already in use.

Common causes

Fixed port collides with a leftover process

A test binds a hardcoded port; a previous test run, a not-yet-stopped server, or a parallel job already owns it, so the bind fails.

Server not shut down between tests

An embedded server started in one test was not cleanly stopped, so the next test that wants the same port cannot bind.

How to fix it

Bind to an ephemeral port

Let the OS assign a free port instead of hardcoding one, then read the chosen port.

# Spring Boot test: random port
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
# or in properties:
server.port=0

Ensure clean shutdown between tests

1. Stop any embedded server in an @AfterEach/@AfterAll teardown.
2. Avoid sharing a single fixed port across parallel test executors.
3. If a port must be fixed, confirm nothing else in the job binds it first.

How to prevent it

• Use random/ephemeral ports in integration tests rather than fixed ones.
• Always tear down embedded servers so ports are released.
• On Latchkey, each job runs on a fresh isolated managed runner, so a leftover process from another build never holds the port -- and self-healing runners auto-retry a transient bind race.

Related guides