...
Eroare Java · Reflecție, module și alte API-uri

java.net.URISyntaxException: Illegal character in query at index 27: https://site.ro/cauta?q=ana maria

Pe scurt

Adresa dată lui new URI(...) sau URI.create conține caractere nepermise neencodate, de obicei spații, diacritice sau |, în query ori în cale. Encodează valorile cu URLEncoder.encode(valoare, StandardCharsets.UTF_8) înainte să le pui în URL.

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

Ce înseamnă

Un URI are reguli stricte: spațiile, ghilimelele, |, { }, <> și caracterele non-ASCII (diacriticele) nu au voie să apară direct, ci doar encodate (spațiul devine %20 sau +, „ș” devine %C8%99). Când new URI(text) găsește un astfel de caracter, aruncă URISyntaxException și îți spune unde: Illegal character in query at index 27, adică în partea de după ?, la poziția 27 din text (numărând de la 0). Variantele: in path (în cale), in fragment (după #), in authority (în domeniu).

Excepția e verificată la new URI. URI.create aruncă în schimb IllegalArgumentException cu același mesaj în interior. Apare frecvent când construiești URL-uri pentru API-uri prin concatenare cu texte de la utilizator, de exemplu termeni de căutare. Clientul HTTP din Java (HttpRequest.newBuilder(URI)) dă aceeași eroare.

De ce apare: cauzele frecvente

1Termen de căutare cu spațiu, neencodat

Greșit
JAVA
String q = "ana maria";
URI uri = new URI("https://site.ro/cauta?q=" + q);
Corect
JAVA
String q = URLEncoder.encode("ana maria", StandardCharsets.UTF_8);
URI uri = new URI("https://site.ro/cauta?q=" + q);

URLEncoder.encode transformă spațiul în + și diacriticele în coduri %XX, permise în query.

2Spațiu sau diacritice în cale

Greșit
JAVA
URI uri = new URI("https://site.ro/produse/cafea boabe");
Corect
JAVA
URI uri = new URI("https", "site.ro", "/produse/cafea boabe", null);
// devine https://site.ro/produse/cafea%20boabe

Constructorul cu mai multe părți encodează singur caracterele nepermise din cale.

3Caractere speciale lipite din alte surse

Greșit
JAVA
URI uri = URI.create("https://api.site.ro/filtre?tag=java|spring");
Corect
JAVA
String tag = URLEncoder.encode("java|spring", StandardCharsets.UTF_8);
URI uri = URI.create("https://api.site.ro/filtre?tag=" + tag);

| nu e permis direct într-un URI; encodat devine %7C.

Repară tu

Repară eroarea, direct în pagină

Programul construiește adresa unei căutări pe site din termenul introdus de utilizator, dar se oprește cu URISyntaxException: Illegal character in query. Encodează termenul, ca programul să afișeze Cerere: https://site.ro/cauta?q=ana+maria și Parametru: q=ana+maria.

Codul care dă eroarea
JAVA
import java.net.*;
import java.nio.charset.StandardCharsets;

public class Main {
    public static void main(String[] args) throws URISyntaxException {
        String termen = "ana maria";
        URI cerere = new URI("https://site.ro/cauta?q=" + termen);
        System.out.println("Cerere: " + cerere);
        System.out.println("Parametru: " + cerere.getRawQuery());
    }
}
După reparație, programul afișează
Cerere: https://site.ro/cauta?q=ana+maria
Parametru: q=ana+maria
Indiciu

Trece termenul prin URLEncoder.encode(termen, StandardCharsets.UTF_8) înainte de concatenare.

Alte forme ale mesajului

  • java.net.URISyntaxException: Illegal character in path at index 29: https://site.ro/produse/cafea boabe
  • java.lang.IllegalArgumentException: Illegal character in query at index 27: https://site.ro/cauta?q=ana maria
  • java.net.URISyntaxException: Illegal character in authority at index 8: https://site ro/
  • java.net.URISyntaxException: Expected scheme-specific part at index 6: https:

Cum o eviți pe viitor

  • Nu construi URL-uri prin concatenare cu valori brute: encodează fiecare valoare cu URLEncoder.encode(v, StandardCharsets.UTF_8).
  • Encodează doar valorile, nu tot URL-ul: ?, & și = trebuie să rămână neschimbate.
  • În Spring, folosește UriComponentsBuilder, care encodează corect fiecare parte.
  • Fă trim() pe URL-urile citite din configurări, ca să nu rămână spații la capete.

Întrebări frecvente

De ce URLEncoder pune + în loc de %20?

URLEncoder urmează formatul formularelor HTML, unde spațiul din query devine +. Serverele îl înțeleg corect în query. În cale (path), spațiul trebuie să fie %20, de aceea acolo folosești constructorul URI cu mai multe părți.

Cum citesc index-ul din mesaj?

Numără caracterele din adresa afișată, de la 0. Caracterul de la acea poziție e primul nepermis, de obicei un spațiu.

Erori înrudite

← Toate erorile Java

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ță Java de la zero, cu exerciții la fiecare lecție

Curs Java: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.