--- # === IDENTITY === id: software/debugging/spring-boot-503/2026 canonical_question: "How do I fix 503 Service Unavailable in Spring Boot?" aliases: - "Spring Boot 503 error" - "Spring Boot service unavailable" - "Spring Boot health check failing" - "Spring Boot actuator 503" - "Spring Boot readiness probe failing" - "Spring Boot Kubernetes 503" - "Spring Boot connection pool exhausted" - "Spring Boot thread pool saturated" entity_type: software_reference domain: software > debugging > spring_boot_503 region: global jurisdiction: global temporal_scope: 2020-2026 # === VERIFICATION === last_verified: 2026-05-17 confidence: 0.93 version: 2.1 first_published: 2026-02-17 # === TEMPORAL VALIDITY === temporal_validity: status: stable last_breaking_change: "Spring Boot 4.0 (2025-11) — Framework 7 baseline, HTTP client properties moved to spring.http.clients.*, Actuator endpoint nullability migrated to JSpecify" next_review: 2026-11-13 change_sensitivity: medium # === CONSTRAINTS === constraints: - "Never disable readiness probes to 'fix' 503 — the probe is reporting a real problem; fix the underlying health indicator" - "Virtual threads (Spring Boot 3.2+) eliminate thread-pool exhaustion but do NOT fix connection pool exhaustion or downstream timeouts" - "HikariCP maximum-pool-size must not exceed your database's max_connections divided by number of app instances" - "RestClient (Spring Boot 3.2+) replaces RestTemplate for new code — configure timeouts via ClientHttpRequestFactorySettings since Boot 3.4" - "In Kubernetes, always use separate liveness, readiness, and startup probes — never use a single /actuator/health for all three" - "Connection leak detection (leak-detection-threshold) must be enabled in production — default is disabled" # === SKIP CONDITIONS === skip_this_unit_if: - condition: "Error is 502 Bad Gateway (upstream proxy/load balancer issue, not the Spring Boot app itself)" use_instead: "Check reverse proxy (nginx, ALB, Envoy) logs and upstream configuration" - condition: "Error is 504 Gateway Timeout (proxy timeout, not application 503)" use_instead: "Increase proxy timeout or optimize slow endpoint response time" - condition: "Application returns 500 Internal Server Error (unhandled exception, not service unavailable)" use_instead: "software/debugging/spring-boot-npe/2026" # === AGENT HINTS === inputs_needed: - key: deployment_env question: "Where is the Spring Boot app deployed?" type: choice options: ["Kubernetes", "AWS ECS/Fargate", "Bare metal/VM", "Docker Compose", "Cloud Run/App Engine"] - key: spring_boot_version question: "Which Spring Boot version are you using?" type: choice options: ["2.x", "3.0-3.1", "3.2+"] - key: symptom_pattern question: "Is the 503 intermittent under load or constant?" type: choice options: ["Intermittent under load", "Constant on every request", "Only during startup/deployment", "After running for hours/days"] # === DISTRIBUTION === canonical_source: "https://knowledgelib.io/software/debugging/spring-boot-503/2026" suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-05-17)" # === RELATED UNITS === related_kos: related_to: - id: "software/debugging/postgresql-connection-pool/2026" label: "PostgreSQL Connection Pool Exhaustion" - id: "software/debugging/kubernetes-crashloopbackoff/2026" label: "Kubernetes CrashLoopBackOff Debugging" - id: "software/debugging/spring-boot-npe/2026" label: "Spring Boot NullPointerException Debugging" solves: - id: "software/debugging/kubernetes-pod-pending/2026" label: "Kubernetes Pod Pending (when 503 stems from probe-driven endpoint removal)" often_confused_with: - id: "software/debugging/spring-boot-npe/2026" label: "Spring Boot 500 errors (unhandled exceptions, not 503 service unavailable)" - id: "software/debugging/nodejs-econnrefused/2026" label: "Node.js ECONNREFUSED (connection refused, not 503 from the Spring Boot app itself)" # === SOURCES (8 authoritative sources) === sources: - id: src1 title: "Spring Boot Actuator Health Indicators" author: Spring.io url: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html type: official_docs published: 2026-04-01 reliability: authoritative - id: src2 title: "Spring Boot Production-Ready Features" author: Spring.io url: https://docs.spring.io/spring-boot/reference/actuator/ type: official_docs published: 2026-04-01 reliability: authoritative - id: src3 title: "HikariCP Connection Pool Configuration" author: HikariCP url: https://github.com/brettwooldridge/HikariCP type: official_docs published: 2025-06-01 reliability: authoritative - id: src4 title: "Spring Boot Kubernetes Deployment Guide" author: Spring.io url: https://docs.spring.io/spring-boot/reference/deployment/cloud.html type: official_docs published: 2026-04-01 reliability: authoritative - id: src5 title: "Tomcat Thread Pool and Connection Handling" author: Apache Tomcat url: https://tomcat.apache.org/tomcat-10.1-doc/config/executor.html type: official_docs published: 2025-07-01 reliability: authoritative - id: src6 title: "Spring Boot Circuit Breaker with Resilience4j" author: Resilience4j url: https://resilience4j.readme.io/docs type: official_docs published: 2025-05-01 reliability: high - id: src7 title: "Spring Boot RestClient Timeout Configuration" author: Baeldung url: https://www.baeldung.com/spring-rest-timeout type: technical_blog published: 2025-09-01 reliability: high - id: src8 title: "Spring Boot 4.0 Release Notes (HTTP client property migration, JSpecify nullability)" author: Spring.io url: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes type: official_docs published: 2026-04-01 reliability: authoritative --- # How to Fix 503 Service Unavailable in Spring Boot ## TL;DR - **Bottom line**: 503 in Spring Boot means the server is up but can't handle requests -- top causes: (1) Kubernetes readiness probe failing, (2) HikariCP connection pool exhausted, (3) Tomcat thread pool saturated, (4) downstream service timeout cascading. - **Key tool/command**: `curl http://localhost:8080/actuator/health` -- check which health indicator is `DOWN`. - **Watch out for**: Default HikariCP pool is only 10 connections -- production workloads need 20-50+ depending on throughput. Virtual threads do NOT fix this. - **Works with**: Spring Boot 2.x / 3.x / 4.x (Framework 7), embedded Tomcat/Jetty/Undertow, Kubernetes/ECS/Cloud Run deployments. ## Constraints - Never disable readiness probes to "fix" 503 -- the probe is reporting a real problem; fix the underlying health indicator. [src1] - Virtual threads (Spring Boot 3.2+) eliminate thread-pool exhaustion but do NOT fix connection pool exhaustion or downstream timeouts. [src5] - HikariCP `maximum-pool-size` must not exceed your database's `max_connections` divided by number of app instances. [src3] - RestClient (Spring Boot 3.2+) replaces RestTemplate for new code -- configure timeouts via `ClientHttpRequestFactorySettings` since Boot 3.4. [src7] - In Kubernetes, always use separate liveness, readiness, and startup probes -- never use a single `/actuator/health` for all three. [src4] - Connection leak detection (`leak-detection-threshold`) must be enabled in production -- default is disabled. [src3] ## Quick Reference | # | 503 Root Cause | Likelihood | Symptom | Fix | |---|---|---|---|---| | 1 | Readiness probe failing | ~30% of cases | K8s removes pod from service; actuator shows DOWN | Fix failing health indicator or increase probe timeout [src1, src4] | | 2 | Connection pool exhausted | ~25% of cases | `HikariPool-1 - Connection is not available, request timed out after 30000ms` | Increase pool size, fix connection leaks, enable leak detection [src3] | | 3 | Thread pool saturated | ~15% of cases | All 200 Tomcat threads busy, new requests rejected with `RejectedExecutionException` | Increase `server.tomcat.threads.max`, enable virtual threads on 3.2+, or fix slow endpoints [src5] | | 4 | Downstream service timeout | ~15% of cases | Requests hang waiting for external API, threads pile up | Add timeouts + circuit breaker with Resilience4j [src6, src7] | | 5 | OutOfMemoryError | ~5% of cases | GC thrashing, eventual unresponsiveness | Increase heap or fix memory leak [src2] | | 6 | Database unavailable | ~5% of cases | Health check on DB returns DOWN | Fix DB connection or configure `management.health.db.enabled=false` [src1] | | 7 | Disk space full | ~3% of cases | DiskSpaceHealthIndicator returns DOWN | Free disk or set `management.health.diskspace.threshold` [src1] | | 8 | Graceful shutdown in progress | ~2% of cases | App is shutting down, rejecting new requests | Expected during rolling updates; check K8s `terminationGracePeriodSeconds` [src4] | ## Decision Tree > Full script: [decision-tree.txt](scripts/decision-tree.txt) (27 lines) ``` START ├── Is /actuator/health returning DOWN? │ ├── YES → Which health indicator is DOWN? │ │ ├── db → Database connection issue [src1] │ │ │ └── FIX: Check DB connectivity, increase pool size │ │ ├── diskSpace → Disk full [src1] │ │ │ └── FIX: Free disk, adjust threshold │ │ ├── custom → Application-specific health check [src1] │ │ │ └── FIX: Debug the custom HealthIndicator │ │ └── readinessState → App not ready [src4] │ │ └── FIX: Check startup dependencies │ └── NO → Health is UP but still getting 503? │ ├── Check load balancer health check path │ └── Check if 503 comes from reverse proxy (nginx/ALB) ├── Connection pool errors in logs? │ ├── YES → HikariCP exhausted [src3] │ │ └── FIX: spring.datasource.hikari.maximum-pool-size=30 │ └── NO ↓ ├── Thread rejection in logs? │ ├── YES → Tomcat threads saturated [src5] │ │ └── FIX: server.tomcat.threads.max=400 or enable virtual threads (3.2+) │ └── NO ↓ ├── Downstream calls timing out? │ ├── YES → Cascading failure [src6] │ │ └── FIX: Add RestClient/WebClient timeouts + circuit breaker │ └── NO → Check JVM metrics (GC pauses, heap usage) └── DEFAULT → Enable actuator + micrometer metrics ``` ## Step-by-Step Guide ### 1. Check actuator health endpoint Determine which component is reporting DOWN. This is always the first diagnostic step. [src1] ```bash # Check overall health curl -s http://localhost:8080/actuator/health | jq # Check detailed health (requires config) # application.properties: management.endpoint.health.show-details=always management.health.readinessstate.enabled=true management.health.livenessstate.enabled=true curl -s http://localhost:8080/actuator/health | jq # Output shows which component is DOWN ``` **Verify**: `curl -s http://localhost:8080/actuator/health | jq .status` -> expected: `"UP"` after fix ### 2. Check connection pool status HikariCP default pool size of 10 is almost always too small for production. Size based on your actual concurrency. [src3] ```properties # application.properties — HikariCP tuning spring.datasource.hikari.maximum-pool-size=30 spring.datasource.hikari.minimum-idle=10 spring.datasource.hikari.connection-timeout=30000 spring.datasource.hikari.idle-timeout=600000 spring.datasource.hikari.max-lifetime=1800000 spring.datasource.hikari.leak-detection-threshold=60000 ``` **Verify**: `curl -s http://localhost:8080/actuator/metrics/hikaricp.connections.active | jq .measurements` -> active should be below maximum-pool-size ### 3. Check and tune Tomcat thread pool Default 200 threads can be exhausted under sustained load. On Spring Boot 3.2+, consider virtual threads instead of increasing the pool. [src5] ```properties # application.properties — Tomcat tuning server.tomcat.threads.max=400 server.tomcat.threads.min-spare=20 server.tomcat.accept-count=100 server.tomcat.max-connections=10000 server.tomcat.connection-timeout=20000 # Spring Boot 3.2+ — virtual threads (eliminates thread pool exhaustion) spring.threads.virtual.enabled=true ``` **Verify**: `curl -s http://localhost:8080/actuator/metrics/tomcat.threads.busy | jq .measurements` -> busy threads should be well below max ### 4. Add timeouts to downstream calls Every outbound HTTP call must have connect and read timeouts. Without them, one slow downstream service can consume all threads. [src6, src7] ```java // Spring Boot 3.2+ — RestClient with timeouts (preferred over RestTemplate) @Configuration public class RestClientConfig { @Bean public RestClient restClient(RestClient.Builder builder) { return builder .requestFactory(ClientHttpRequestFactories.get( ClientHttpRequestFactorySettings.DEFAULTS .withConnectTimeout(Duration.ofSeconds(5)) .withReadTimeout(Duration.ofSeconds(10)) )) .build(); } } ``` ```java // Spring Boot 2.x-3.1 — RestTemplate with timeouts @Configuration public class RestClientConfig { @Bean public RestTemplate restTemplate() { var factory = new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(Duration.ofSeconds(5)); factory.setReadTimeout(Duration.ofSeconds(10)); return new RestTemplate(factory); } } ``` **Verify**: Test with a slow downstream mock; request should fail with timeout instead of hanging indefinitely ### 5. Configure Kubernetes probes correctly Use three separate probes: startup (for slow-starting apps), liveness (restart if stuck), and readiness (stop traffic if not ready). [src4] ```yaml # Kubernetes deployment — proper probe configuration [src4] containers: - name: app livenessProbe: httpGet: path: /actuator/health/liveness port: 8080 initialDelaySeconds: 30 periodSeconds: 10 failureThreshold: 3 readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 15 periodSeconds: 5 failureThreshold: 3 startupProbe: httpGet: path: /actuator/health/liveness port: 8080 initialDelaySeconds: 10 periodSeconds: 5 failureThreshold: 30 # 30 x 5s = 150s max startup ``` **Verify**: `kubectl describe pod ` -> no probe failure events after deployment ## Code Examples ### Java: Circuit breaker for downstream services > Full script: [java-circuit-breaker-for-downstream-services.java](scripts/java-circuit-breaker-for-downstream-services.java) (30 lines) ```java // Input: Downstream API that may be slow/unavailable // Output: Graceful degradation instead of 503 cascade @Service public class PaymentService { private final RestTemplate restTemplate; # ... (see full script) ``` ### Java: Custom health indicator with graceful degradation ```java // Input: Non-critical external dependency (e.g., cache, search index) // Output: Health check that degrades to WARNING without failing readiness @Component public class SearchHealthIndicator implements HealthIndicator { private final RestClient restClient; @Override public Health health() { try { restClient.get().uri("/ping") .retrieve().toBodilessEntity(); return Health.up().build(); } catch (Exception e) { // Report degraded but don't fail readiness [src1] return Health.up() .withDetail("search", "degraded: " + e.getMessage()) .build(); } } } ``` ## Anti-Patterns ### Wrong: No timeouts on HTTP calls ```java // ❌ BAD — one slow downstream call can exhaust all threads [src6] String result = restTemplate.getForObject("http://slow-service/api", String.class); // Default: no timeout → thread hangs indefinitely ``` ### Correct: Always set timeouts + circuit breaker ```java // ✅ GOOD — bounded timeout prevents thread exhaustion [src6, src7] var factory = new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(Duration.ofSeconds(3)); factory.setReadTimeout(Duration.ofSeconds(10)); var restTemplate = new RestTemplate(factory); ``` ### Wrong: Default connection pool size for production ```properties # ❌ BAD — HikariCP default is 10 connections # Under load: "Connection is not available, request timed out after 30000ms" ``` ### Correct: Size pool for production workload ```properties # ✅ GOOD — scale pool to match expected concurrency [src3] spring.datasource.hikari.maximum-pool-size=30 spring.datasource.hikari.leak-detection-threshold=60000 ``` ### Wrong: Using virtual threads and assuming connection pool issues are solved ```properties # ❌ BAD — virtual threads handle more concurrent requests but each still needs # a DB connection. 1000 virtual threads + 10-connection pool = massive contention [src3, src5] spring.threads.virtual.enabled=true # spring.datasource.hikari.maximum-pool-size=10 (default) ``` ### Correct: Virtual threads with appropriately sized connection pool ```properties # ✅ GOOD — scale connection pool alongside virtual threads [src3] spring.threads.virtual.enabled=true spring.datasource.hikari.maximum-pool-size=50 spring.datasource.hikari.leak-detection-threshold=60000 ``` ### Wrong: Single health endpoint for all K8s probes ```yaml # ❌ BAD — liveness and readiness have different semantics [src4] livenessProbe: httpGet: path: /actuator/health # includes readiness checks! readinessProbe: httpGet: path: /actuator/health # same endpoint ``` ### Correct: Separate probe endpoints ```yaml # ✅ GOOD — each probe checks what it should [src4] livenessProbe: httpGet: path: /actuator/health/liveness # only: is the JVM alive? readinessProbe: httpGet: path: /actuator/health/readiness # only: can it accept traffic? startupProbe: httpGet: path: /actuator/health/liveness # give app time to start ``` ## Common Pitfalls - **Readiness probe too aggressive**: If `initialDelaySeconds` is too short, K8s fails the probe before Spring Boot finishes starting. Fix: use `startupProbe` for slow-starting apps (Spring Boot 2.3+). [src4] - **Connection pool exhaustion from leaks**: Connections not returned to pool (e.g., exception before `close()`). Fix: enable `leak-detection-threshold` and use try-with-resources. [src3] - **Health check includes non-critical dependencies**: If Redis health check fails, the entire app reports DOWN. Fix: group non-critical health checks under readiness only, not liveness. Or use a custom HealthIndicator that reports degraded instead of DOWN. [src1] - **No graceful shutdown**: Kubernetes sends SIGTERM but app doesn't drain in-flight requests. Fix: `server.shutdown=graceful` + `spring.lifecycle.timeout-per-shutdown-phase=30s`. [src4] - **Thread pool defaults too low**: Tomcat default is 200 threads. Under sustained load, all threads can be consumed. Fix: increase `server.tomcat.threads.max` or enable virtual threads on Spring Boot 3.2+. [src5] - **Virtual threads with pinned carriers**: Synchronized blocks and native methods pin virtual threads to carrier threads. Under high concurrency, pinning can re-introduce thread exhaustion. Fix: replace `synchronized` with `ReentrantLock` in hot paths. [src5] - **Connection pool too large for DB**: Setting `maximum-pool-size=200` across 10 instances = 2000 connections, which exceeds most database `max_connections` defaults (typically 100-200). Fix: calculate `pool_size = max_connections / instance_count`. [src3] ## Diagnostic Commands ```bash # Check health details curl -s http://localhost:8080/actuator/health | jq # Check individual probe endpoints (K8s) curl -s http://localhost:8080/actuator/health/liveness | jq curl -s http://localhost:8080/actuator/health/readiness | jq # Check HikariCP metrics (requires micrometer) curl -s http://localhost:8080/actuator/metrics/hikaricp.connections.active | jq curl -s http://localhost:8080/actuator/metrics/hikaricp.connections.pending | jq curl -s http://localhost:8080/actuator/metrics/hikaricp.connections.timeout | jq # Check Tomcat threads curl -s http://localhost:8080/actuator/metrics/tomcat.threads.current | jq curl -s http://localhost:8080/actuator/metrics/tomcat.threads.busy | jq # JVM memory curl -s http://localhost:8080/actuator/metrics/jvm.memory.used | jq # Check if virtual threads are active (Spring Boot 3.2+) curl -s http://localhost:8080/actuator/metrics/executor.active | jq # Thread dump for diagnosing stuck threads curl -s http://localhost:8080/actuator/threaddump | jq '.threads[] | select(.state=="WAITING" or .state=="TIMED_WAITING") | .threadName' # Kubernetes: check pod events for probe failures kubectl describe pod | grep -A5 "Events:" kubectl get events --field-selector involvedObject.name= ``` ## Version History & Compatibility | Spring Boot | Status | Key Changes for 503 Debugging | |---|---|---| | 2.3+ | EOL (commercial support only) | Readiness/liveness probes, graceful shutdown introduced [src4] | | 2.4+ | EOL (commercial support only) | Startup probe support, K8s probe grouping | | 3.0+ | EOL OSS | Jakarta EE 10 namespace (javax -> jakarta), Tomcat 10.1 | | 3.2+ | EOL OSS | Virtual threads GA, RestClient GA, improved observability with Micrometer Tracing [src5, src7] | | 3.3+ | EOL OSS | Enhanced health group configuration, structured logging | | 3.4+ | EOL OSS (no further patches) | RestClient timeout via `ClientHttpRequestFactorySettings`, SSL bundle auto-reload [src7] | | 3.5+ | Maintenance (OSS through 2026-06-30) | Final 3.x minor. Actuator `processInfo` now exposes virtual-thread counts on JDK 24+ — direct signal for thread saturation [src1, src2] | | 4.0+ | Current (Framework 7) | HTTP client properties moved to `spring.http.clients.*` (`spring.http.client.*` deprecated). Actuator endpoint nullability migrated to JSpecify (`org.jspecify.annotations.Nullable`) — affects custom HealthIndicators [src8] | ## When to Use / When Not to Use | Debug 503 When | Look Elsewhere When | Use Instead | |---|---|---| | Actuator health shows DOWN | 502 Bad Gateway (upstream proxy error) | Check nginx/ALB/Envoy logs | | Connection pool logs show exhaustion | 504 Gateway Timeout (proxy timeout) | Increase proxy timeout settings | | K8s pod keeps restarting | 500 Internal Server Error (unhandled exception) | Check application logs for stack trace | | Load increases -> intermittent 503 | Consistent 503 on every request from startup | Check application.properties misconfiguration | | After deploying new version | 503 from CDN or static assets | Check CDN origin configuration | ## Important Caveats - Virtual threads (Spring Boot 3.2+ with `spring.threads.virtual.enabled=true`) can eliminate thread-pool exhaustion issues but don't fix connection pool or downstream timeout problems. With virtual threads, you may actually hit connection pool limits faster because more concurrent requests can proceed simultaneously. - Health endpoint 503 from Kubernetes readiness is by design -- it tells K8s to stop sending traffic. Don't disable it; fix the underlying health check. - In Spring Boot 3.x, `management.health.readinessstate.enabled` defaults to true in Kubernetes environments (auto-detected via `KUBERNETES_SERVICE_HOST` env var). - RestClient (Spring Boot 3.2+) is the recommended replacement for RestTemplate. Since Spring Boot 3.4, timeouts can be configured via `ClientHttpRequestFactorySettings` rather than manual factory creation. - `spring.threads.virtual.enabled=true` causes `SimpleAsyncTaskExecutor` to be used, which ignores `spring.task.execution.pool.*` properties. Thread pool sizing properties have no effect when virtual threads are enabled. - On Spring Boot 4.0+, HTTP client timeout properties moved namespace: use `spring.http.clients.*` instead of `spring.http.client.*` (still works but emits deprecation warnings). [src8] - On Spring Boot 3.5+ running on JDK 24+, virtual-thread pinning from `synchronized` blocks is largely fixed at the JVM level, but `synchronized` blocks holding I/O still serialize traffic. Custom HealthIndicators that synchronize over external calls can still spike latency under load. ## Related Units - [PostgreSQL Connection Pool Exhaustion](/software/debugging/postgresql-connection-pool/2026) - [Kubernetes CrashLoopBackOff Debugging](/software/debugging/kubernetes-crashloopbackoff/2026) - [Kubernetes Pod Pending](/software/debugging/kubernetes-pod-pending/2026) - [Spring Boot NullPointerException](/software/debugging/spring-boot-npe/2026) - [Node.js ECONNREFUSED](/software/debugging/nodejs-econnrefused/2026)