Skip to content
javahacks.dev
Spring Boot

Fix Spring Boot Port 8080 Already in Use on Any System

Find the process holding port 8080 on macOS, Linux and Windows, stop it, or move Spring Boot to another port, and fix the tests that collide.

6 min read
Summarize in AI
Flat illustration of a log with a failing line and a wrench, with the Spring Boot, Gradle and OpenJDK logos.

The application stops during startup with a clear message:

Text
Web server failed to start. Port 8080 was already in use.

Action:

Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.

Something else is listening on 8080. Most of the time that something is the last run of your own application, still alive because the IDE detached it or a terminal tab was closed. This post finds the process on each system and lists the other places a port gets taken. The wider startup checklist is application failed to start.

Find who owns the port

On macOS and Linux:

Shell
lsof -i :8080

The output lists a command, a PID and the user. On Linux, ss -ltnp 'sport = :8080' gives the same information. Stop the process with kill <pid>, and use kill -9 only if a plain kill is ignored, since it skips shutdown hooks.

On Windows, in Command Prompt:

Shell
netstat -ano | findstr :8080
taskkill /PID 12345 /F

Replace 12345 with the PID in the last column of the first command.

Check Docker before Java

A container published with -p 8080:8080 holds the host port even though no Java process is visible. List them:

Shell
docker ps --format '{{.Names}}  {{.Ports}}'

Stop the container or change its published port. On Linux, a rootless Docker or a local reverse proxy can also be the owner, which lsof or ss shows.

Cause: your own app, twice

IDE run configurations that start a second instance, a spring-boot:run left in a background terminal and DevTools restarts that fail to release the socket all leave a copy behind. If lsof shows java as the command, check the command line with ps -p <pid> -o args= to confirm it is yours before you kill it.

Move the port instead

When you intend to run two instances, change the port per instance:

src/main/resources/application.propertiesproperties
server.port=8081

Or without editing files: ./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081, or SERVER_PORT=8081 in the environment. Setting server.port=0 asks the operating system for any free port, which is what you want in tests.

Tests that collide

Two test classes that each start the web server on a fixed port fail intermittently when run in parallel. Use a random port:

java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class OrderApiTest {

    @LocalServerPort int port;
}

@LocalServerPort injects the port that was chosen. A slice such as @WebMvcTest never opens a port, so prefer it where you can; see the testing strategy.

The exact message, and the line that names the port

Spring Boot's failure analyzer replaces a long Tomcat stack trace with a short report. Starting a second instance of the same application on a port that is taken produces this on Spring Boot 4.0.9:

Text
***************************
APPLICATION FAILED TO START
***************************

Description:

Web server failed to start. Port 8096 was already in use.

Action:

Identify and stop the process that's listening on port 8096 or configure this application to listen on another port.

The port in the message is whichever port was configured, not necessarily 8080; the title of this post uses the default. The report appears when the web server cannot bind, and it means another process holds the socket. The process does not have to be a Java program. Docker containers publishing the port, a database admin tool, a previous run of your own application that did not shut down, and an operating-system service all count.

Find the owner on each system

The command depends on the platform, and each one prints the process id that owns the listening socket.

Shell
# macOS and Linux
lsof -nP -iTCP:8080 -sTCP:LISTEN
ss -ltnp 'sport = :8080'          # Linux, shows the process name

# Windows (PowerShell)
Get-NetTCPConnection -LocalPort 8080 | Select-Object OwningProcess
Shell
docker ps --format '{{.Names}}  {{.Ports}}' | grep 8080

The Docker command is worth running first on a development machine, because a container with -p 8080:8080 holds the port on the host even when nothing visible is running. If the owner is an old copy of your application, stop it with its normal mechanism, not kill -9, so connections drain. If it is another application you need, move yours.

Move the port without editing the code

Spring Boot reads the port from several places, and the command line wins, so the quickest change touches nothing in the repository.

Shell
java -jar app.jar --server.port=8081
SERVER_PORT=8081 java -jar app.jar

In Maven or Gradle development runs, pass it as an argument: ./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081. For a permanent change, set server.port in the configuration for that environment. Use server.port=0 to ask the operating system for any free port; the log then prints Tomcat started on port 60054, with the real number.

Prevent the collision in tests

Tests that start the web server on a fixed port collide with each other when run in parallel and with the application running in the IDE. Use a random port in every test that starts a server.

java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class OrderApiIT {

    @LocalServerPort int port;

    @Test
    void healthIsUp() {
        String body = RestClient.create().get().uri("http://localhost:" + port + "/actuator/health")
                .retrieve().body(String.class);
        assertThat(body).contains("UP");
    }
}

@LocalServerPort injects the port that was chosen. With MOCK environment tests, no port is opened at all, which is the cheapest kind and the right default for controller tests.

When the port is free and it still fails

If lsof shows nothing and the error persists, three causes remain. A permission problem: ports below 1024 need privileges on Linux, so a service configured for port 80 fails as a normal user with a different message ("Permission denied"), and setcap or a reverse proxy is the answer. A bind address conflict: the application is configured to bind to a specific address with server.address, and that address does not exist on the machine, as happens when a configuration for a cloud host is run on a laptop. And a management port that collides: management.server.port set to the same value as server.port or to another taken port reports the same message naming a different number, so read the number in the message instead of assuming it is the main one.

Make local ports predictable for a team

Port clashes come from several projects using the same default. Agree a port map for the team and write it in the repository: the API on 8080, the admin application on 8081, the mock server on 8082, so that nobody guesses. Put the number in application-local.properties or in the Compose file, and avoid commands that depend on a particular port being free. For services that start many things at once, a Compose file with explicit port mappings documents the choice and lets a developer change one number without editing the code.

For the cases where a stale process is the cause, add a helper to the README so nobody searches for it each time: a one-line command that prints the owner of the port and, only on request, stops it. Keep the stop step manual, since killing the owner of a port can stop something unrelated.

Where this does not apply

If the message names a different problem, such as a bind failure on a privileged port below 1024 on Linux, the cause is permissions, not a conflict; run on a high port and map it in the container or proxy. The Spring Boot web server reference lists the server.* properties, including server.address for binding to a single interface. The project setup this error interrupts is described in Spring Boot from first project to production, and a stale container that holds the port is a close relative of a Docker image that will not start. The Spring Boot how-to guides documents the behavior in detail.

Also inDebugging
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.