Spring Boot server.port Command Line Argument Override Explained

Mar 26, 2026

I needed to run multiple instances of my Spring Boot application on different ports for testing, but I kept getting port conflicts. Every time I tried to start a second instance, it failed because port 8080 was already in use.

The Problem

I had this simple Spring Boot application:

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

My application.properties had:

server.port=8080

When I tried to run a second instance, I got this error:

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

I needed a way to override the port without changing the properties file.

First Attempt: Environment Variable

I tried setting an environment variable:

SERVER_PORT=8081 java -jar myapp.jar

But this didn’t work. The application still used port 8080.

I realized I was using the wrong property name. Spring Boot properties use dot notation, so I should have used:

SERVER_PORT=8081 java -jar myapp.jar

Wait, that’s still wrong. The correct environment variable format for server.port is SERVER_PORT (Spring Boot converts dots to underscores and uppercase). But I wanted something more direct.

The Solution: Command Line Arguments

Spring Boot treats command-line arguments as property overrides. This means any argument passed with -- prefix will override the corresponding property in application.properties.

java -jar myapp.jar --server.port=8081

This worked immediately. The application started on port 8081.

Why This Works

Spring Boot has a specific order for property resolution. Command-line arguments have the highest priority in the property source hierarchy:

Command line arguments (highest priority)
Java System properties
OS environment variables
Application properties outside the jar
Application properties inside the jar (lowest priority)

When I pass --server.port=8081, Spring Boot converts it to a property and applies it after reading application.properties, effectively overriding the default value.

Using in IntelliJ IDEA

I also needed to test this in IntelliJ. In my Run Configuration:

Open Run > Edit Configurations
Select my Spring Boot application
In the “Program arguments” field, I added:

--server.port=8081

The full configuration looked like:

Main class: com.example.Application
Program arguments: --server.port=8081

Verifying the Port Override

To confirm the port override worked, I created a simple endpoint:

@RestController
@RequestMapping("/multiple-instance")
public class InstanceController {

    @Value("${server.port}")
    private String port;

    @GetMapping("/ping")
    public ResponseEntity<String> ping() {
        return ResponseEntity.ok("Instance is up and running on port " + port);
    }
}

Then I tested it:

curl localhost:8081/multiple-instance/ping

Output:

Instance is up and running on port 8081

Running Multiple Instances

Now I can run multiple instances easily:

# Instance 1
java -jar myapp.jar --server.port=8080

# Instance 2 (in another terminal)
java -jar myapp.jar --server.port=8081

# Instance 3
java -jar myapp.jar --server.port=8082

Each instance runs on its own port without any code changes or multiple configuration files.

Key Takeaways

Command-line arguments with -- prefix override Spring Boot properties
Command-line arguments have the highest priority in Spring Boot’s property resolution
This approach works for any Spring Boot property, not just server.port
Useful for testing, running multiple instances, or deploying to different environments

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!