Introduction

Spring Boot starts the embedded Tomcat server on port 8080 by default. Changing that port is usually a configuration task, and the right method depends on whether you want a fixed project default, an environment override, or a value chosen at runtime.

Change the Port in application.properties

The simplest approach is to set server.port in your application configuration.

server.port=9090

After restarting the application, the embedded server will listen on port 9090 instead of 8080.

If the project uses YAML, the equivalent is:

server:
  port: 9090

This is the best choice when the application should consistently run on the same non-default port in a given environment.

Override the Port from the Command Line

A command-line override is useful for local development, temporary testing, or deployment scripts.

java -jar app.jar --server.port=8085

This value overrides the packaged configuration for that specific launch. It is convenient when you need to run multiple Spring Boot services on one machine without editing each project file.

Use Environment Variables

In containerized or cloud environments, environment variables are often cleaner than editing configuration files.

export SERVER_PORT=9001
java -jar app.jar

Spring Boot automatically maps SERVER_PORT to server.port. This is a common pattern for Docker, Kubernetes, and platform-managed deployments.

Programmatic Configuration

If the port must be decided from application logic, configure the web server factory in Java.

1import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
2import org.springframework.boot.web.server.WebServerFactoryCustomizer;
3import org.springframework.context.annotation.Bean;
4import org.springframework.context.annotation.Configuration;
5
6@Configuration
7public class ServerConfig {
8
9    @Bean
10    public WebServerFactoryCustomizer<TomcatServletWebServerFactory> customizer() {
11        return factory -> factory.setPort(7070);
12    }
13}

This is more flexible than plain properties, but it should be used only when configuration alone is not sufficient. Hard-coding infrastructure choices in Java is usually less maintainable than external configuration.

Special Case: Random Port

For tests, it is often useful to let Spring Boot choose a random free port.

server.port=0

With this value, the operating system selects an available port. In integration tests, Spring can inject that port so your test client knows where to connect.

1import org.springframework.boot.test.context.SpringBootTest;
2import org.springframework.boot.test.web.server.LocalServerPort;
3
4@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
5class DemoApplicationTests {
6
7    @LocalServerPort
8    int port;
9}

This avoids port collisions on shared CI runners.

How Spring Boot Chooses the Final Value

Spring Boot resolves configuration from multiple sources with a defined precedence order. A command-line argument can override a property file, and an environment variable can override a packaged default. That matters because an application may appear to ignore application.properties when the actual value is coming from somewhere else.

If the server still starts on an unexpected port, inspect:

• command-line arguments
• environment variables
• active profiles
• container or deployment platform configuration

Common Pitfalls

• Changing application.properties and expecting the running process to update without restart does not work. The server port is chosen at startup time.
• Forgetting that environment variables or launch arguments override property files can make the configuration appear inconsistent. Check the full configuration chain.
• Hard-coding the port in Java when a property would do adds unnecessary rigidity. Prefer external configuration unless runtime logic is truly required.
• Binding the application to a port already in use causes startup failure. Verify local conflicts before assuming Spring Boot ignored the setting.
• Using a random port in development without discovering the chosen value makes testing awkward. Reserve server.port=0 mainly for automated tests and controlled scenarios.

Summary

• The default embedded Tomcat port in Spring Boot is 8080.
• The usual fix is setting server.port in properties, YAML, or launch arguments.
• Environment variables are a clean option for containers and hosted deployments.
• Programmatic customization is available when the port depends on runtime logic.
• If the port seems wrong, check configuration precedence before changing code.