...
Eroare Spring Boot · Validare

must be a well-formed email address

Pe scurt

Este mesajul implicit al lui @Email: valoarea nu arată ca o adresă de email. Atenție: @Email acceptă null și textul gol, deci pentru un email obligatoriu pune și @NotBlank.

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

Ce înseamnă

@Email verifică forma adresei (o parte locală, @, un domeniu). Dacă valoarea nu respectă forma, mesajul implicit este must be a well-formed email address.

Capcana frecventă: ca aproape toate adnotările Bean Validation, @Email consideră valide null și textul gol "". Regula generală este că fiecare adnotare verifică un singur lucru, iar „câmpul trebuie să existe” e treaba lui @NotBlank / @NotNull. Un formular trimis cu emailul gol trece deci de validare, iar problema apare mai târziu, la trimiterea mesajelor sau ca înregistrări fără email în bază.

Verificarea lui @Email este și permisivă: acceptă ana@exemplu (fără punct în domeniu), pentru că e o adresă validă tehnic. Dacă ai reguli mai stricte, adaugă regexp sau @Pattern. Singura confirmare reală rămâne un email de verificare.

De ce apare: cauzele frecvente

1Email gol acceptat

Greșit
JAVA
record Abonare(@Email String email) { }
// {"email": ""} trece
Corect
JAVA
record Abonare(@NotBlank @Email String email) { }

@NotBlank cere o valoare, @Email îi verifică forma.

2Adresa are o greșeală de scriere

Greșit
JAVA
{"email": "ana.exemplu.ro"}
Corect
JAVA
{"email": "ana@exemplu.ro"}

Fără @, valoarea nu e o adresă.

Repară tu

Repară eroarea, direct în pagină

Ruta POST /abonare validează emailul cu @Email, dar un formular trimis cu emailul gol trece și răspunde Abonat: fără adresă. Fă emailul obligatoriu, ca cererea cu email gol să primească 400, iar cea cu ana@exemplu.ro să răspundă Abonat: ana@exemplu.ro.

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 jakarta.validation.Valid;
import jakarta.validation.constraints.*;
import org.springframework.web.bind.MethodArgumentNotValidException;

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

record Abonare(@Email String email) {
}

@RestController
class AbonareController {
    @PostMapping("/abonare")
    String aboneaza(@Valid @RequestBody Abonare a) {
        return "Abonat: " + a.email();
    }
}

@RestControllerAdvice
class EroriValidare {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    ResponseEntity<Map<String, String>> invalid(MethodArgumentNotValidException e) {
        Map<String, String> erori = new TreeMap<>();
        e.getBindingResult().getFieldErrors()
                .forEach(f -> erori.put(f.getField(), f.getDefaultMessage()));
        return ResponseEntity.badRequest().body(erori);
    }
}
După reparație, programul afișează
Tomcat started on port 8080 (http)
Started Application
POST /abonare → 400
{"email":"must not be blank"}
POST /abonare → 200
Abonat: ana@exemplu.ro
Indiciu

@Email verifică doar forma; obligativitatea o exprimă altă adnotare.

Alte forme ale mesajului

  • must be a well-formed email address (rejected value [ana])

Cum o eviți pe viitor

  • Combină mereu regulile de formă (@Email, @Pattern, @Size) cu @NotBlank / @NotNull când câmpul e obligatoriu.
  • Scrie mesaje proprii pentru utilizatori.
  • Pentru siguranță deplină, confirmă adresa printr-un email cu link.
  • Testează explicit valorile goale, nu doar pe cele greșite.

Întrebări frecvente

De ce @Email acceptă textul gol?

Prin convenție, constrângerile Bean Validation tratează valorile absente ca valide, ca să poată fi combinate. Obligativitatea se exprimă separat.

Acceptă @Email adrese fără punct în domeniu?

Da, ana@localhost este o adresă validă tehnic. Pentru reguli stricte adaugă @Email(regexp = ".+@.+\\..+").

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.