rustfs/rustfs · error

UUID must be a valid header value

Error message

UUID must be a valid header value

What it means

Raised in the RPC client when a generated UUID (challenge or correlation value) cannot be converted into an http HeaderValue. UUIDs are always valid header bytes, so hitting this means an invariant break in UUID formatting/encoding at the auth layer.

Source

Thrown at crates/ecstore/src/cluster/rpc/client.rs:378

    fn call(&mut self, mut request: HttpRequest<ReqBody>) -> Self::Future {
        let authenticated = self.audience.as_ref().is_some_and(|_| {
            request
                .headers()
                .get(RPC_AUTH_VERSION_HEADER)
                .and_then(|value| value.to_str().ok())
                == Some(RPC_AUTH_VERSION_V2)
        });
        let challenge = authenticated.then(Uuid::new_v4);
        let sent_state = request
            .extensions()
            .get::<PeerReplayStateSnapshot>()
            .map(|snapshot| snapshot.0)
            .unwrap_or_default();
        if let (Some(audience), Some(challenge)) = (self.audience.as_deref(), challenge) {
            // The challenge is independently HMAC-authenticated by the response proof. It is not
            // part of v2 so old peers ignore it, while a new peer can safely advertise its epoch.
            request.headers_mut().insert(
                RPC_BOOT_EPOCH_CHALLENGE_HEADER,
                challenge.to_string().parse().expect("UUID must be a valid header value"),
            );
            if let (Some(boot_epoch), Some(timestamp), Some(content_sha256)) = (
                sent_state.boot_epoch,
                request.headers().get(TIMESTAMP_HEADER).and_then(|value| value.to_str().ok()),
                request
                    .headers()
                    .get(RPC_CONTENT_SHA256_HEADER)
                    .and_then(|value| value.to_str().ok()),
            ) {
                match gen_tonic_replay_scope_headers(audience, request.uri().path(), timestamp, content_sha256, boot_epoch) {
                    Ok(headers) => request.headers_mut().extend(headers),
                    Err(error) => debug!(error = %error, "could not attach replay-scoped RPC signature"),
                }
            }
        }

        let audience = self.audience.clone();

View on GitHub (pinned to 5dca076efe)

Solutions

1. Fail the request setup; the auth header cannot be built safely
2. Log which UUID field failed conversion for debugging
3. No retry: deterministic conversion failure, likely a code/version bug

When it happens

Trigger: Thrown at crates/ecstore/src/cluster/rpc/client.rs:359 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of rustfs/rustfs@5dca076efe (2026-08-20). Data as JSON: /api/errors/9fc99f92f6b027dc. Report an issue: GitHub.