Skip to content

Static route segments containing a literal non-ASCII character never match #25671

Closed

Description

@faucheux-saxess-ag

Description of the bug

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:

  1. 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).
  2. @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.

Minimal reproducible example

vaadin-umlaut-route-sscce.zip

Versions

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).

Activity

  1. totally-not-ai commented on Sep 11, 2026

    @totally-not-ai
    Contributor

    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 (int i = 0; i < result.length(); i++) {
        char c = result.charAt(i);
        if (c > 127) {
            hasMultibyte = true;
        }
        bytes[i] = (byte) c;   // <- also narrows characters that were never escaped
    }
    if (hasMultibyte) {
        return new String(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.

  2. added a commit that references this issue on Sep 14, 2026
    357fffc
  3. added a commit that references this issue on Sep 15, 2026
    9e407f9
  4. vaadin-bot commented on Sep 29, 2026

    @vaadin-bot
    Collaborator

    This ticket/PR has been released with Vaadin 25.4.0-alpha1.

  5. added a commit that references this issue on Oct 1, 2026
    59f9cb2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions