You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Static route segments containing a literal non-ASCII character never match #25671
com.vaadin.flow.internal.UrlUtil#decodeURIComponent(String) (added in #22791, used since 24.9.12 / 25.1) is designed to reconstruct multi-byte
UTF-8 characters from consecutive %XX percent-encoded escapes. It applies
its byte-reassembly step unconditionally to any character with code
point > 127 in the input, even when that character was never
percent-encoded in the first place — i.e. when it reaches the method as a
literal, already-decoded Unicode character. This corrupts the character
into U+FFFD (replacement character).
This single root cause has two independent, user-visible consequences:
Static route segments containing a literal non-ASCII character never
match, even when the exact same string is used both to register the
route and to look it up (PathUtil#getSegmentsListWithDecoding, used by RouteSegment#getNavigationRouteTarget for static-segment matching).
@WildcardParameter route parameter values get corrupted a second,
independent time during deserialization
(ParameterDeserializer#deserializeRouteParameters), even in cases
where the value was extracted correctly up to that point.
Expected behavior
A route containing a literal non-ASCII path segment should match on the
same, immediate, server-side resolution attempt as an equivalent ASCII
route — no extra client round-trip should be necessary.
Vaadin Flow 25.2.4
Likely present in any 24.9.12+ / 25.1+ Flow version, since that is when PathUtil#getSegmentsListWithDecoding / UrlUtil#decodeURIComponent
were introduced (#22791).
Thanks for the unusually precise report, @faucheux-saxess-ag — your analysis is
correct, this is a real bug and the root cause is exactly where you point.
What is wrong
UrlUtil.decodeURIComponent(String) decodes the %XX escapes into chars and
then, as a second step, reinterprets the whole result as UTF-8 bytes as soon
as any char in it has a code point above 127:
for (inti = 0; i < result.length(); i++) {
charc = result.charAt(i);
if (c > 127) {
hasMultibyte = true;
}
bytes[i] = (byte) c; // <- also narrows characters that were never escaped
}
if (hasMultibyte) {
returnnewString(bytes, StandardCharsets.UTF_8);
}
A literal ü (U+00FC) becomes the single byte 0xFC, which is not valid UTF-8
on its own, so it is replaced with U+FFFD. Characters above U+00FF are worse:
they are truncated by the (byte) cast, so 日本 decodes to �,.
Verified against the current main:
"grüße" → gr��e
"日本" → �,
"mix ü %C3%BC" → mix � ü (the escaped one is fine, the literal one is not)
"gr%C3%BC%C3%9Fe" → grüße (correct, this is the case the method was written for)
The method documents itself as the equivalent of JavaScript's decodeURIComponent(), and decodeURIComponent("grüße") in a browser returns "grüße" unchanged — so the behaviour is also a deviation from its own contract.
Why it surfaces in routing
HttpServletRequest#getPathInfo() is already URL-decoded by the servlet
container, and that value is what BootstrapHandler / JavaScriptBootstrapHandler
put into the Location. So on the initial server-side resolution a route
like @Route("grüße") arrives as literal characters, and PathUtil.getSegmentsListWithDecoding() (used by RouteSegment#getNavigationRouteTarget for static-segment matching since #22791)
corrupts it before the lookup — the registered segment grüße and the looked-up
segment gr��e never compare equal, hence the 404 and the extra client
round-trip you observed. Client-side navigations send the still-encoded pathname,
which is why they work.
The @WildcardParameter case is the same root cause one layer further down: RouteSegment stores the raw segments as the parameter value, and ParameterDeserializer#deserializeRouteParameters runs decodeURIComponent over
them — literal in, corrupted out.
TransferUtil#getDecodedFileName and ResourceFolderUtil use the same method
and are affected by the same defect for non-ASCII input.
Proposed solution
Decode only what is actually escaped. Consecutive %XX escapes are collected
into a byte sequence that is decoded as UTF-8 (so multi-byte characters split
over several escapes still work), while every character that was not escaped is
appended as-is and never narrowed to a byte. A string with no escapes at all is
returned unchanged.
That is a single, contained change in UrlUtil.decodeURIComponent and fixes both
symptoms at once; no change is needed in PathUtil, RouteSegment or ParameterDeserializer.
I have opened a draft PR with that fix plus regression tests: UrlUtilTest
(literal non-ASCII, and literal mixed with escaped), PathUtilTest (segments of
an already decoded path) and RouterTest (a static @Route with a non-ASCII
segment resolves for both the literal and the percent-encoded location, and a @WildcardParameter keeps a literal non-ASCII value). All five assertions fail
on main and pass with the fix; the full flow-server suite (5269 tests) is
green.
One thing worth a maintainer's opinion: the method stays lenient about invalid
input, where the browser's decodeURIComponent() throws a URIError. For
example %80 on its own still decodes to U+FFFD rather than raising an error.
That is the pre-existing behaviour and routing relies on not throwing for
arbitrary URLs, so I kept it.
Activity
totally-not-ai commentedon Sep 11, 2026
Thanks for the unusually precise report, @faucheux-saxess-ag — your analysis is
correct, this is a real bug and the root cause is exactly where you point.
What is wrong
UrlUtil.decodeURIComponent(String)decodes the%XXescapes into chars andthen, as a second step, reinterprets the whole result as UTF-8 bytes as soon
as any char in it has a code point above 127:
A literal
ü(U+00FC) becomes the single byte0xFC, which is not valid UTF-8on its own, so it is replaced with
U+FFFD. Characters above U+00FF are worse:they are truncated by the
(byte)cast, so日本decodes to�,.Verified against the current
main:"grüße"→gr��e"日本"→�,"mix ü %C3%BC"→mix � ü(the escaped one is fine, the literal one is not)"gr%C3%BC%C3%9Fe"→grüße(correct, this is the case the method was written for)The method documents itself as the equivalent of JavaScript's
decodeURIComponent(), anddecodeURIComponent("grüße")in a browser returns"grüße"unchanged — so the behaviour is also a deviation from its own contract.Why it surfaces in routing
HttpServletRequest#getPathInfo()is already URL-decoded by the servletcontainer, and that value is what
BootstrapHandler/JavaScriptBootstrapHandlerput into the
Location. So on the initial server-side resolution a routelike
@Route("grüße")arrives as literal characters, andPathUtil.getSegmentsListWithDecoding()(used byRouteSegment#getNavigationRouteTargetfor static-segment matching since #22791)corrupts it before the lookup — the registered segment
grüßeand the looked-upsegment
gr��enever compare equal, hence the 404 and the extra clientround-trip you observed. Client-side navigations send the still-encoded pathname,
which is why they work.
The
@WildcardParametercase is the same root cause one layer further down:RouteSegmentstores the raw segments as the parameter value, andParameterDeserializer#deserializeRouteParametersrunsdecodeURIComponentoverthem — literal in, corrupted out.
TransferUtil#getDecodedFileNameandResourceFolderUtiluse the same methodand are affected by the same defect for non-ASCII input.
Proposed solution
Decode only what is actually escaped. Consecutive
%XXescapes are collectedinto a byte sequence that is decoded as UTF-8 (so multi-byte characters split
over several escapes still work), while every character that was not escaped is
appended as-is and never narrowed to a byte. A string with no escapes at all is
returned unchanged.
That is a single, contained change in
UrlUtil.decodeURIComponentand fixes bothsymptoms at once; no change is needed in
PathUtil,RouteSegmentorParameterDeserializer.I have opened a draft PR with that fix plus regression tests:
UrlUtilTest(literal non-ASCII, and literal mixed with escaped),
PathUtilTest(segments ofan already decoded path) and
RouterTest(a static@Routewith a non-ASCIIsegment resolves for both the literal and the percent-encoded location, and a
@WildcardParameterkeeps a literal non-ASCII value). All five assertions failon
mainand pass with the fix; the fullflow-serversuite (5269 tests) isgreen.
One thing worth a maintainer's opinion: the method stays lenient about invalid
input, where the browser's
decodeURIComponent()throws aURIError. Forexample
%80on its own still decodes toU+FFFDrather than raising an error.That is the pre-existing behaviour and routing relies on not throwing for
arbitrary URLs, so I kept it.
fix: decode only percent-encoded escapes in decodeURIComponent (#25672)…
fix: decode only percent-encoded escapes in decodeURIComponent (vaadi…
vaadin-bot commentedon Sep 29, 2026
This ticket/PR has been released with Vaadin 25.4.0-alpha1.
fix: decode only percent-encoded escapes in decodeURIComponent (#25672)…