vectordotdev/vector · error

username must be valid UTF-8.

Error message

username must be valid UTF-8.

What it means

When building an HTTP(S) proxy from a configured or environment-derived proxy URL, Vector decodes the percent-encoded username from the URL authority with urlencoding::decode(...).expect("username must be valid UTF-8.") (lib/vector-core/src/config/proxy.rs). Percent-decoding yields raw bytes; if those bytes are not valid UTF-8 the decode fails and the expect panics while constructing the proxy interceptor chain.

Source

Thrown at lib/vector-core/src/config/proxy.rs:167

            no_proxy,
        }
    }

    fn build_proxy(
        &self,
        proxy_scheme: &'static str,
        proxy_url: Option<&String>,
    ) -> Result<Option<Proxy>, InvalidUri> {
        proxy_url
            .as_ref()
            .map(|url| {
                url.parse().map(|parsed| {
                    let mut proxy = Proxy::new(self.interceptor().intercept(proxy_scheme), parsed);
                    if let Ok(authority) = Url::parse(url)
                        && let Some(password) = authority.password()
                    {
                        let decoded_user = urlencoding::decode(authority.username())
                            .expect("username must be valid UTF-8.");
                        let decoded_pw =
                            urlencoding::decode(password).expect("Password must be valid UTF-8.");
                        let mut authorization =
                            Authorization::basic(&decoded_user, &decoded_pw).0.encode();
                        authorization.set_sensitive(true);
                        proxy.set_header(PROXY_AUTHORIZATION, authorization);
                    }
                    proxy
                })
            })
            .transpose()
    }

    fn http_proxy(&self) -> Result<Option<Proxy>, InvalidUri> {
        self.build_proxy("http", self.http.as_ref())
    }

    fn https_proxy(&self) -> Result<Option<Proxy>, InvalidUri> {

View on GitHub (pinned to 3708c39b12)

Solutions

1. Re-encode the proxy username as valid UTF-8 percent-encoding (encode the UTF-8 bytes of the real username, e.g. user%C3%A9 for 'useré')
2. Verify the URL with a standard parser first: python3 -c 'import urllib.parse; print(urllib.parse.unquote("..."))' or curl -x — if those also fail, the URL bytes are wrong
3. If the credentials really contain non-UTF-8 bytes, change the proxy account password to a UTF-8-safe one, since RFC 3986 userinfo and HTTP Basic auth both assume UTF-8/ASCII

Example fix

# before
export https_proxy='http://user%FF%FE:pass@proxy.internal:8080'

# after (é = U+00E9 = UTF-8 bytes C3 A9)
export https_proxy='http://user%C3%A9:pass@proxy.internal:8080'

fn proxy_userinfo_is_utf8(url: &str) -> bool {
    let Ok(parsed) = url::Url::parse(url) else { return false };
    if let Some(user) = parsed.username() {
        if let Ok(bytes) = percent_encoding::percent_decode_str(user).decode_utf8() { let _ = bytes; } else { return false; }
    }
    true
}
// assert!(proxy_userinfo_is_utf8(&env_var));

When it happens

Trigger: Setting http_proxy/https_proxy/all_proxy (or the proxy config fields) to a URL whose userinfo contains percent-encoded sequences that decode to invalid UTF-8, e.g. http://user%FF%FE:pass@proxy:8080. The panic occurs on proxy construction during HTTP client builder setup (Proxy::from_env / interceptor setup), i.e. typically at topology build time or on first request, and only when a password is also present (the decode runs inside the password branch).

Common situations: Proxy credentials containing non-UTF-8 bytes (legacy LDAP/system accounts) pasted as raw percent-escape sequences; hand-crafted proxy URLs where % sequences are mistyped (e.g. %FF from a truncated copy/paste); CI environments injecting proxy env vars from a secrets store that mangles encoding.

Related errors

• Password must be valid UTF-8.
• not a valid path
• No ability to glob
• path and query should never fail to parse
• Serializer does not support JSON

AI-assisted analysis of vectordotdev/vector@3708c39b12 (2026-08-20). Data as JSON: /api/errors/c79fa76405c0fcb1. Report an issue: GitHub.