...
Eroare Spring Boot · Proiect, dependențe și migrarea la Boot 3

GET /actuator/health → 503 {"status":"DOWN"}

Pe scurt

Cel puțin un HealthIndicator (bază de date, disc, un serviciu extern sau unul scris de tine) raportează DOWN, deci starea totală e DOWN, iar răspunsul are codul 503. Activează show-details ca să vezi componenta problematică, apoi repar-o (de obicei configurarea).

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

/actuator/health combină starea tuturor bean-urilor HealthIndicator: db (conexiunea la bază), diskSpace, ping, plus indicatorii proprii. Dacă unul raportează DOWN, starea totală devine DOWN, iar endpoint-ul răspunde cu codul 503 Service Unavailable. Load balancer-ele și Kubernetes (readiness/liveness) folosesc exact acest cod, deci o instanță DOWN nu mai primește trafic sau e repornită.

Implicit, răspunsul conține doar {"status":"DOWN"}, fără motiv. Cu management.endpoint.health.show-details=always (local) sau when-authorized (producție) vezi fiecare componentă, cu detaliile ei, de exemplu "furnizor":{"status":"DOWN","details":{"motiv":"URL lipsă"}}.

Cauzele tipice: baza de date nu răspunde sau are credențiale greșite, discul aproape plin, un serviciu extern căzut sau o proprietate necesară unui indicator propriu, scrisă greșit.

De ce apare: cauzele frecvente

1Proprietate scrisă greșit pentru un indicator

Greșit
JAVA
app.furnizor-url=https://furnizor.example
# indicatorul citește app.furnizor.url
Corect
JAVA
app.furnizor.url=https://furnizor.example

Cheia trebuie să fie exact cea citită de indicator.

2Baza de date indisponibilă

Greșit
JAVA
spring.datasource.password=parola-veche
# db: DOWN
Corect
JAVA
spring.datasource.password=${DB_PASSWORD}

Indicatorul db încearcă o conexiune reală; credențialele greșite îl fac DOWN.

Repară tu

Repară eroarea, direct în pagină

GET /actuator/health răspunde 503 DOWN. Detaliile arată că indicatorul furnizor nu găsește URL-ul furnizorului, deși configurarea îl conține. Rescrie application.properties în cod (comentariu /* application.properties ... */), păstrând celelalte chei și corectând cheia URL-ului, ca starea să devină UP.

Codul care dă eroarea
JAVA
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.*;
import org.springframework.beans.factory.annotation.*;
import org.springframework.http.*;
import java.util.*;
import org.springframework.boot.actuate.health.*;

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

@Component
class FurnizorHealthIndicator implements HealthIndicator {
    private final String url;

    FurnizorHealthIndicator(@Value("${app.furnizor.url:}") String url) {
        this.url = url;
    }

    @Override
    public Health health() {
        if (url.isBlank()) {
            return Health.down().withDetail("motiv", "URL lipsă").build();
        }
        return Health.up().withDetail("url", url).build();
    }
}

/* application.properties
management.endpoint.health.show-details=always
app.furnizor-url=https://furnizor.example
*/
După reparație, programul afișează
Tomcat started on port 8080 (http)
Started Application
GET /actuator/health → 200
{"status":"UP","components":{"furnizor":{"status":"UP","details":{"url":"https://furnizor.example"}},"ping":{"status":"UP"}}}
Indiciu

Compară cheia din @Value cu cea din application.properties: punct vs liniuță.

Alte forme ale mesajului

  • {"status":"OUT_OF_SERVICE"}
  • "db":{"status":"DOWN","details":{"error":"org.springframework.jdbc.CannotGetJdbcConnectionException"}}
  • "diskSpace":{"status":"DOWN"}

Cum o eviți pe viitor

  • Activează detaliile health în mediile de test, ca să vezi imediat componenta DOWN.
  • Folosește grupuri separate pentru liveness și readiness (management.endpoint.health.group.*), ca o dependență externă căzută să nu repornească aplicația.
  • Scrie indicatori proprii care întorc detalii clare la DOWN.
  • Verifică health în pipeline după fiecare deploy.

Întrebări frecvente

De ce 503 și nu 200 cu DOWN?

Spring Boot mapează DOWN și OUT_OF_SERVICE la 503, ca load balancer-ele să poată reacționa doar după cod.

Pot ascunde un indicator din health?

Da, cu management.health.<nume>.enabled=false, dar fă asta doar dacă dependența chiar nu contează pentru disponibilitatea aplicației.

Erori înrudite

← Toate erorile Spring Boot

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață Spring Boot de la zero, cu exerciții la fiecare lecție

Curs Spring Boot și REST API: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 18 lecții sunt gratuite.