Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Spring Boot will not start because port 8080 is already taken

ErrorWeb server failed to start. Port 8080 was already in use.

Short answer

Spring Boot listens on 8080 unless told otherwise, and only one process can own a port. Find what holds 8080. If it is another service, give each one its own server.port. If it is a test, use a random port. Stopping the old process works for a stale run.

  • Applies to Spring Boot 3.x and 4.x, Java 17 and 21, Gradle 8.x and 9.x, macOS, Linux, Windows
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the system who owns the port right now. On Windows, use netstat -ano | findstr :8080 and read the last column, which is the process id.

    lsof -nP -iTCP:8080 -sTCP:LISTEN
  2. 2Match what you see, then jump to its fix

    1. 1The process holding 8080 is another Java process of yours, started from a different projectTwo services on the same machine both use the default portFix
    2. 2The failure only appears when tests run, or when two tests start a server in one buildA test starts the real server on a fixed portFix
    3. 3A tool, a demo or a throw-away run keeps hitting a busy portYou need any free port, and the number does not matterFix

What does the error look like?

  • 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.

Cause 1 of 3

Two services on the same machine both use the default port

1Check

Every Spring Boot web app defaults to 8080. Microservices run side by side on a laptop collide unless each sets its own port.

grep -rn "server.port\|server:" src/main/resources/

2Fix

Give each service a distinct port in its own configuration.

# src/main/resources/application.properties
server.port=8081

3Verify

Start the app and read the port in the startup log.

./gradlew bootRun

Confirmed by docs.spring.io

Did this fix it?

Cause 2 of 3

A test starts the real server on a fixed port

1Check

A web test that uses the defined port tries 8080 each time. A dev server left running, or a second test class, makes it fail.

grep -rn "SpringBootTest" src/test/ | head

2Fix

Run the test web environment on a random port and inject the real number.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ApiTests {

    @LocalServerPort
    int port;
}

3Verify

Run the tests twice in a row, with the dev server still up.

./gradlew test

Confirmed by docs.spring.io

Did this fix it?

Cause 3 of 3

You need any free port, and the number does not matter

1Check

Look for a port that is hard coded in a profile or environment variable. An environment variable named SERVER_PORT is read by Spring Boot as server.port.

echo $SERVER_PORT

2Fix

Set the port to 0 so the operating system picks a free one, then read the real number from the startup log or from WebServerInitializedEvent.

# application.properties
server.port=0

3Verify

Start two copies at once. Both run, each on its own port.

./gradlew bootRun

Confirmed by docs.spring.io

Did this fix it?

How do I stop it coming back?

  • Put a unique server.port in every service of a multi-service project and list them in the project README.
  • Use RANDOM_PORT in every web integration test.
  • Stop dev runs from the IDE or terminal before starting another, instead of closing the window.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.