Spring Boot will not start because port 8080 is already taken
Web 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.
Fix it fast
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:LISTEN2Match what you see, then jump to its fix
- 1
The 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
The 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
A tool, a demo or a throw-away run keeps hitting a busy portYou need any free port, and the number does not matterFix
- 1
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=80813Verify
Start the app and read the port in the startup log.
./gradlew bootRunConfirmed by docs.spring.io
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/ | head2Fix
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 testConfirmed by docs.spring.io
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_PORT2Fix
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=03Verify
Start two copies at once. Both run, each on its own port.
./gradlew bootRunConfirmed by docs.spring.io
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:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Nuclear Home VideoA video-streaming Android app built from scratch, engineered for smooth playback.
Related fixes
Back end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack end
A scanner flags jackson-databind: how to upgrade it in Gradle
jackson-databind vulnerability reported by a dependency scanner
Find where the old jackson-databind comes from, then raise it.
3 causes, each with a fixBack end
Gradle cannot resolve spring-boot-gradle-plugin after a Spring Boot 3 upgrade
Plugin [id: 'org.springframework.boot', version: '3.0.1'] was not found in any of the following sources
Spring Boot 3 needs Java 17 or newer and a recent Gradle, and its Gradle plugin is published on the Gradle Plugin Portal.
3 causes, each with a fixBack end
bootJar cannot find the main class of a Spring Boot project
Main class name has not been configured and it could not be resolved
The Spring Boot Gradle plugin looks in the main source set's output for a class with a public static void main method.
2 causes, each with a fixBack end
Spring Boot fails at startup with an error processing a condition on an auto-configuration
java.lang.IllegalStateException: Error processing condition on org.springframework.boot.autoconfigure.jdbc.JndiDataSourceAutoConfiguration
This message only says Spring Boot failed while evaluating an auto-configuration condition.
3 causes, each with a fixBack end
Swagger UI URL shows the Whitelabel Error Page in Spring Boot
Whitelabel Error Page when opening /swagger-ui.html
The Whitelabel page means Spring found no handler for that address.
3 causes, each with a fix