Graceful Shutdown

Graceful Shutdown in Spring Boot: Ensuring Smooth Application Termination

Learn how to implement graceful shutdown in Spring Boot applications to ensure a smooth and reliable termination process.


In the world of modern application development, ensuring a smooth and reliable shutdown process is crucial. Spring Boot, a popular Java framework, provides built-in features to gracefully handle application shutdowns. In this comprehensive guide, we will explore the concept of graceful shutdown in Spring Boot, discuss its importance, and demonstrate implementation with code samples. Also, we will look into the Actuator’s shutdown endpoint, and highlight key considerations for your applications.

What is a Graceful Shutdown?

Graceful shutdown refers to the process of terminating an application in a controlled manner, allowing it to complete any ongoing tasks, release resources, and ensure data integrity. Instead of abruptly terminating the application, graceful shutdown ensures that all processes are gracefully stopped, preventing any potential data corruption or loss.

Enabling Graceful Shutdown in Spring Boot

Starting with Spring Boot 2.3, there’s a new feature called “graceful shutdown” for the embedded web servers it supports. These servers include Tomcat, Jetty, Undertow, and Netty, for both traditional and reactive programming.

To enable graceful shutdown, you just need to add one line to your file:


With this setting, when you stop the server, it won’t accept new requests, ensuring a smooth shutdown process.

By default, the server will shut down immediately, without waiting for ongoing requests to finish. However, during graceful shutdown, the server can wait for a specified time for ongoing requests to complete their work.

You can control this grace period using the spring.lifecycle.timeout-per-shutdown-phase property. For example:


In this example, the server will wait up to two minutes for active requests to complete before shutting down. The default wait time is 30 seconds.


This feature ensures that your Spring Boot application handles ongoing tasks gracefully during the shutdown, which helps prevent data loss and disruptions for your users. You can adjust the grace period as needed for your specific application.

Spring Boot Actuator Shutdown Endpoint

To enable graceful shutdown via Spring Boot Actuator, you need to follow these steps:

Step 1: Add Actuator Dependency

In pom.xml, add the Spring Boot Actuator dependency:


Step 2: Update Application Properties

In your, make sure you have the following configuration to enable graceful shutdown and also, to expose the shutdown endpoint that can be triggered:

# Properties to enable graceful shutdown and to configure grace period

# Properties to enable and expose actuator shutdown endpoint

Step 3: Run and Test

Now, run your Spring Boot application. You should be able to access the Actuator endpoints, including the /actuator/shutdown (or your custom endpoint if you implemented one).

To gracefully shut down the application, make an HTTP POST request to the shutdown endpoint using tools like curl, or Postman:

POST http://localhost:8080/actuator/shutdown

After the request, your application will start the graceful shutdown process. It will stop accepting new requests, but it will give ongoing requests a grace period to finish their work before the application shuts down completely.


The /actuator/shutdown endpoint may require proper authentication and authorization configurations in production environments to prevent unauthorized access to it.

Testing Graceful Shutdown

Discover testing strategies to ensure that your graceful shutdown implementation works as expected.

  1. Simulating a Graceful Shutdown Request: Learn how to simulate a graceful shutdown request by invoking the Actuator endpoint programmatically or using tools like cURL or Postman. Observe the application’s behavior during the shutdown process.
  2. Handling Ongoing Requests: Understand how the application handles ongoing requests during the graceful shutdown phase. Verify that active requests are allowed to complete before the application shuts down. Increment or decrement the timeout period if required.
  3. Verifying Resource Cleanup: Validate the resource cleanup process during a graceful shutdown. Ensure that database connections, file handles, and network connections are properly released, maintaining system integrity.


What is graceful shutdown in Spring Boot?

Graceful shutdown is a feature in Spring Boot that allows the application to finish ongoing tasks and handle active requests before shutting down. It ensures that the application exits gracefully without abruptly terminating requests, reducing the risk of data loss or client disruptions.

What are the benefits of using graceful shutdown in Spring Boot?

Graceful shutdown ensures that your application finishes processing ongoing requests before shutting down, reducing the likelihood of data loss and ensuring a smooth experience for your users or clients.

What is the default timeout for graceful shutdown in Spring Boot?

By default, the grace period for the application to complete ongoing requests is 30 seconds. You can adjust this value using the spring.lifecycle.timeout-per-shutdown-phase property in your configuration file.

How do I test the graceful shutdown in my Spring Boot application?

To test graceful shutdown, start your Spring Boot application, send some test requests to simulate ongoing work, and then trigger the shutdown by either using the Actuator /actuator/shutdown endpoint or a custom shutdown endpoint you may have implemented.

Can I use a custom endpoint for graceful shutdown in Spring Boot?

Yes, you can create a custom shutdown controller in your application, and upon receiving a request to that endpoint, you can programmatically initiate the shutdown process. This allows you to have more control over the shutdown behavior.

What happens to incoming requests during a graceful shutdown?

During a graceful shutdown, the application stops accepting new requests. However, ongoing requests are allowed to finish their work within the grace period before the application finally shuts down.

What happens if an ongoing request takes longer than the grace period during shutdown?

If an ongoing request exceeds the grace period specified in the spring.lifecycle.timeout-per-shutdown-phase, Spring Boot may forcefully terminate the request to ensure that the application can shut down within a reasonable time frame.

Does graceful shutdown affect scheduled tasks or background jobs?

Yes, during the graceful shutdown, scheduled tasks or background jobs may be interrupted if they are still running within the grace period. Make sure to handle these tasks properly to avoid unexpected behavior.

Things to Consider

When working with Spring Boot graceful shutdown, there are several important considerations to keep in mind to ensure a smooth and reliable shutdown process. Here are the key things to consider:

  1. Grace Period Duration: Set an appropriate grace period for your application’s shutdown using the spring.lifecycle.timeout-per-shutdown-phase property. Consider the time needed for ongoing requests to complete without affecting user experience or data integrity.
  2. Long-Running Tasks: Be mindful of long-running tasks, such as database operations, file processing, or external API calls. Make sure to handle these tasks efficiently to avoid delays during the graceful shutdown process.
  3. Scheduled Tasks and Background Jobs: Take into account any scheduled tasks or background jobs running in your application. Ensure they can gracefully terminate or complete within the grace period to avoid potential disruptions.
  4. Data Consistency: Graceful shutdown should not compromise data consistency. Ensure that your application handles in-flight transactions properly and commits any essential changes before shutting down.
  5. Error Handling: Implement proper error handling during the shutdown process. Log any potential issues or errors encountered during shutdown to aid in debugging and troubleshooting.
  6. Endpoint Access Control: If using the Actuator /actuator/shutdown endpoint or a custom shutdown endpoint, ensure that proper access control mechanisms are in place to prevent unauthorized access.
  7. Monitoring and Logging: Monitor your application’s behavior during the shutdown process. Use application logs and monitoring tools to track performance, detect anomalies, and ensure a successful shutdown.
  8. Graceful Termination of Threads: If your application uses custom threads or thread pools, ensure that they can gracefully terminate and clean up resources during the shutdown.
  9. Graceful Shutdown Testing: Thoroughly test the graceful shutdown behavior of your application. Simulate various scenarios, including different types of requests and long-running tasks, to verify that the shutdown process works as expected.
  10. Graceful Shutdown Hooks: If needed, implement custom hooks or listeners to perform cleanup tasks or notify external systems before shutting down.
  11. Integration with Container Platforms: If deploying your application on container platforms like Kubernetes, ensure that you have proper integration to initiate a graceful shutdown when containers are terminated or scaled down.
  12. Documentation: Document the graceful shutdown process, including the grace period, the potential impact on ongoing tasks, and any specific considerations unique to your application.


In summary, graceful shutdown in Spring Boot ensures a smooth and safe application termination. By properly configuring properties like server.shutdown and spring.lifecycle.timeout-per-shutdown-phase, we allow ongoing tasks to finish, release resources, and maintain data integrity. Prioritizing graceful shutdown enhances application reliability and user experience, showcasing a commitment to seamless operations from start to finish.

Learn More


Interested in learning more?

Check out our blog on dynamic insert and update using Spring Data JPA.

Add a Comment

Your email address will not be published.