How to Fix Spring Boot Health Check Timeout on Render

by

Summary

The deployment failed because the application failed to pass the platform’s health check probe. While the logs show the DispatcherServlet initialized successfully, the orchestration layer (Render) timed out waiting for a 200 OK response from the configured health check endpoint. The application is likely running but is unreachable from the external load balancer, or it is consuming all resources during startup, preventing the web server from responding to the probe.

Root Cause

The failure is driven by a mismatch between the application startup lifecycle and the platform’s readiness probe configuration. Specifically:

  • Endpoint Mismatch: The health check is directed at /api/, but if the Spring Boot application does not have a specific controller mapping for the root of /api/ that returns a 200 OK, the probe receives a 404 Not Found or 405 Method Not Allowed.
  • Slow Warm-up (Cold Start): Spring Boot applications have a heavy startup footprint. If the JVM is still performing JIT compilation or initializing the ApplicationContext, it may not respond to HTTP requests within the platform’s allotted timeout window.
  • Port Misconfiguration: The log indicates the app is listening on port 10000. If the platform expects the app to listen on a dynamic $PORT environment variable and the app is hardcoded to 10000, the health check will fail because the traffic is being routed to the wrong destination.
  • Context Path Issues: If server.servlet.context-path is set in application.properties, the health check path must be adjusted to account for this prefix.

Why This Happens in Real Systems

In production environments, orchestration layers (like Kubernetes, Render, or AWS ECS) use health checks to ensure traffic is only routed to “ready” instances. This prevents the “Black Hole” effect, where a user request is sent to a service that is technically “running” (the process exists) but is not yet “functional” (the web server isn’t accepting connections).

  • Resource Contention: In containerized environments, CPU throttling during startup can delay the web server’s ability to handle the initial handshake.
  • Dependency Blocking: If the application performs a synchronous connection check to a database or a cache during the startup phase, a slow database response will stall the entire startup sequence, causing the health check to time out.

Real-World Impact

  • Deployment Rollback Loops: The platform sees the failure, kills the container, and tries again, leading to a CrashLoopBackOff state.
  • Service Unavailability: Even if the code is perfect, the service remains “Offline” in the eyes of the users.
  • Cascading Failures: If this service is a dependency for other microservices, those services may also start failing due to connection timeouts.

Example or Code

To fix this, ensure you use Spring Boot Actuator to provide a dedicated, lightweight health endpoint and verify your port configuration.

# application.properties

# 1. Enable the health endpoint via Actuator
management.endpoints.web.exposure.include=health
management.endpoint.health.show-details=always

# 2. Ensure the server listens on the port provided by the environment
server.port=${PORT:10000}

# 3. (Optional) Set a context path if needed
# server.servlet.context-path=/api
// A simple fallback controller if Actuator is not used
@RestController
public class HealthCheckController {

    @GetMapping("/api/")
    public ResponseEntity healthCheck() {
        return ResponseEntity.ok("UP");
    }
}

How Senior Engineers Fix It

  1. Implement Actuator: Never rely on a business logic endpoint for health checks. Use spring-boot-starter-actuator to provide the /actuator/health endpoint, which is optimized for minimal overhead.
  2. Decouple Startup from Readiness: Use Liveness and Readiness probes. A “Liveness” probe checks if the process is alive; a “Readiness” probe checks if the app is actually ready to serve traffic (e.g., DB connection is established).
  3. Environment Variable Injection: Always use ${PORT} instead of hardcoding ports to allow the hosting provider to manage networking dynamically.
  4. Observability: Instead of looking at basic logs, senior engineers check JVM metrics and startup duration logs to see if the application is hitting CPU limits during the “warm-up” phase.

Why Juniors Miss It

  • Confusing “Running” with “Ready”: Juniors often assume that if the logs say “Started Application,” the deployment is a success. They fail to realize the Load Balancer has its own criteria for success.
  • Hardcoding Configurations: Juniors tend to hardcode ports and URLs based on their local environment, which fails in the heterogeneous environments of cloud providers.
  • Ignoring the Platform Layer: They focus entirely on the application code and ignore the infrastructure configuration (the health check path, timeout settings, and port mapping) that sits between the code and the user.

Leave a Comment