How to Run Multiple Spring Boot Instances in IntelliJ IDEA

Mar 26, 2026

I needed to test how multiple instances of my Spring Boot application would interact with each other locally. But every time I tried to run the app twice, IntelliJ just stopped the first instance and started a new one.

The problem: I couldn’t figure out how to run the same Spring Boot application multiple times simultaneously in IntelliJ IDEA.

The Goal

I wanted to simulate a scenario where multiple instances of my application run on different ports. This is useful for:

Testing load balancing
Simulating service-to-service communication
Testing distributed features like caching or messaging
Running different configurations side by side

First Attempt: Just Click Run Again

I naively clicked the Run button while the first instance was already running. IntelliJ immediately stopped the first instance and started a new one.

That’s not what I wanted. I needed both instances running at the same time.

The Solution: Multiple Run Configurations

The key insight is that each instance needs its own run configuration with a unique port. IntelliJ doesn’t allow running the same configuration multiple times simultaneously by default.

Here’s how I solved it.

Step 1: Create a REST Endpoint to Identify Instances

First, I created a simple endpoint to verify which instance is responding. This helps confirm that each instance is running on its expected port.

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

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

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

This endpoint returns the port number, so I can tell which instance responded.

Step 2: Create Multiple Run Configurations

In IntelliJ IDEA:

Go to Run → Edit Configurations
Click the + button and select Spring Boot
Configure the first instance:
- Name: MyApp-Instance1
- Main class: Your main application class
- In VM options: -Dserver.port=8081
Click + again to create a second configuration:
- Name: MyApp-Instance2
- Main class: Same main class
- In VM options: -Dserver.port=8082

Now you have two separate run configurations, each with a different port.

Step 3: Run Both Instances

I ran both configurations by right-clicking each one and selecting Run. You can also use the dropdown in the main toolbar to select each configuration.

Both instances started successfully:

Tomcat started on port(s): 8081 (http) with context path ''
Started MyApplication in 2.341 seconds

Tomcat started on port(s): 8082 (http) with context path ''
Started MyApplication in 2.578 seconds

Step 4: Verify Both Instances Are Running

I tested both endpoints to confirm they were working independently:

curl localhost:8081/multiple-instance/ping

Output:

Instance is up and running on port 8081

curl localhost:8082/multiple-instance/ping

Output:

Instance is up and running on port 8082

Both instances were running and responding correctly.

Alternative Approach: Using Spring Profiles

If you need more than just different ports—say, different database connections or feature flags—Spring Profiles are a better solution.

Step 1: Create Profile-Specific Properties

Create separate properties files for each instance:

server:
  port: 8081

spring:
  application:
    name: myapp-instance1

custom:
  setting: value-for-instance-1

server:
  port: 8082

spring:
  application:
    name: myapp-instance2

custom:
  setting: value-for-instance-2

Step 2: Configure Run Configurations with Profiles

In IntelliJ, update your run configurations to use the profiles:

Instance 1:

VM options: -Dspring.profiles.active=instance1

Instance 2:

VM options: -Dspring.profiles.active=instance2

This approach gives you complete control over each instance’s configuration.

Why This Works

IntelliJ IDEA treats each run configuration as a separate process. By creating distinct configurations with different ports, you’re essentially telling IntelliJ: “Run this same application twice, but with different parameters.”

The key is ensuring each instance binds to a different port. If two instances try to use the same port, you’ll get a “Port already in use” error.

Common Pitfalls

Port Already in Use

If you see this error:

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

Check what’s using the port:

lsof -i :8080

Kill the process if needed, or assign a different port.

Services Clashing on the Same Port

If your app uses multiple services (Actuator, WebSocket, etc.), make sure they’re also configured with different ports:

server:
  port: 8081

management:
  server:
    port: 9081  # Actuator on different port

Database Conflicts

If both instances connect to the same database, you might see connection pool exhaustion. Either:

Use separate databases for each instance
Increase the maximum connection pool size
Use an embedded database like H2 for local testing

Summary

To run multiple Spring Boot instances in IntelliJ IDEA:

Create separate run configurations for each instance
Assign unique ports using -Dserver.port=XXXX in VM options
Use Spring Profiles if you need different configurations beyond just ports
Verify each instance is running with a simple health check endpoint

This approach works for any number of instances—just create more run configurations with additional ports.

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!