DioxusLabs/dioxus · error

expected URL to be UTF-8 encoded

Error message

expected URL to be UTF-8 encoded

What it means

Runtime panic inside the desktop asset resolver's custom protocol handler. The request's URI path is percent-decoded and required to be valid UTF-8; `decode_utf8().expect(...)` in resolve_asset_path_from_filesystem panics when the decoded bytes are not UTF-8.

Source

Thrown at packages/asset-resolver/src/native.rs:46

            // If the asset exists in the Android asset manager, return the can't be represented as a path
            // error instead
            if to_java_load_asset(path).is_some() {
                return AssetPathError::CannotRepresentAsPath;
            }
        }

        AssetPathError::NotFound
    })
}

/// Try to resolve the path of an asset from a given URI path.
fn resolve_asset_path_from_filesystem(path: &str) -> Option<PathBuf> {
    // If the user provided a custom asset handler, then call it and return the response if the request was handled.
    // The path is the first part of the URI, so we need to trim the leading slash.
    let mut uri_path = PathBuf::from(
        percent_encoding::percent_decode_str(path)
            .decode_utf8()
            .expect("expected URL to be UTF-8 encoded")
            .as_ref(),
    );

    // If the asset doesn't exist, or starts with `/assets/`, then we'll try to serve out of the bundle
    // This lets us handle both absolute and relative paths without being too "special"
    // It just means that our macos bundle is a little "special" because we need to place an `assets`
    // dir in the `Resources` dir.
    //
    // If there's no asset root, we use the cargo manifest dir as the root, or the current dir
    if !uri_path.exists() || uri_path.starts_with("/assets/") {
        let bundle_root = get_asset_root();
        let relative_path = uri_path.strip_prefix("/").unwrap();
        uri_path = bundle_root.join(relative_path);
    }

    // If the asset exists, return it
    uri_path.exists().then_some(uri_path)
}

View on GitHub (pinned to 393d190a80)

Solutions

1. Fix the asset reference generating the malformed percent-encoded URL
2. Ensure referenced asset filenames are valid UTF-8
3. Upgrade dioxus-desktop if a newer version returns an error response instead of panicking on undecodable paths

Example fix

// before (malformed reference in rsx)
rsx! { img { src: "assets/icon%FF.png" } }

// after
rsx! { img { src: asset!("/assets/icon.png") } }

When it happens

Trigger: Any asset request whose percent-encoded path decodes to invalid UTF-8 (e.g. a reference containing %FF%FE) hitting the desktop custom protocol when the webview loads an asset.

Common situations: Broken href/src values produced by string concatenation; browser prefetch or extension probes with malformed URLs; asset filenames copied from non-UTF-8 filesystems into references.

Related errors

• Failed to get asset manager
• Failed to get asset manager as object
• Invalid asset manager
• Head element to exist
• Body element to exist

AI-assisted analysis of DioxusLabs/dioxus@393d190a80 (2026-08-16). Data as JSON: /api/errors/5746f70cacce2fcd. Report an issue: GitHub.