rustfs/rustfs · error · TokenError

failed to read the Connect registration token

Error message

failed to read the Connect registration token

What it means

Loading a Connect registration token with RegistrationToken::from_reader failed at the I/O layer before any parsing: the std::io::Error raised while reading up to 16 KiB+1 bytes is wrapped unchanged as this variant's source (registration.rs:77-80). Inspect the wrapped error for the real cause - NotFound, PermissionDenied, UnexpectedEof, and so on.

Source

Thrown at rustfs/src/connect/registration.rs:122

        Ok(Self {
            registration_token_uid: document.registration_token_uid,
            registration_token_secret: Zeroizing::new(document.registration_token_secret),
            organization_uid: document.organization_uid,
            cluster_uid: document.cluster_uid,
            challenge_nonce: document.challenge_nonce,
            expires_unix: document.expires_unix,
        })
    }

    pub(crate) fn secret(&self) -> &str {
        &self.registration_token_secret
    }
}

#[derive(Debug, thiserror::Error)]
pub enum TokenError {
    #[error("failed to read the Connect registration token")]
    Read(#[source] std::io::Error),
    #[error("Connect registration token configuration is invalid")]
    Invalid(#[source] serde_json::Error),
    #[error("Connect registration token secret must be 32-byte unpadded base64url")]
    SecretShape,
    #[error("Connect registration token configuration exceeds 16 KiB")]
    TooLarge,
    #[error("Connect registration token fields do not match the protocol schema")]
    Shape,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
pub(crate) struct RegistrationRequest<'a> {
    protocol_version: &'static str,
    request_id: &'a str,
    registration_token_uid: &'a str,
    registration_token_secret: &'a str,

View on GitHub (pinned to 201c653dcd)

Solutions

1. Match on TokenError::Read and log the wrapped io::Error - it carries the real OS-level cause.
2. Verify the path exists and the service user can read it (stat the file as that user).
3. Re-provision or re-download the token if it was rotated out or never written.
4. For pipe-based readers, keep the writer open until EOF.

Example fix

// before
let token = RegistrationToken::from_reader(File::open(&path)?)?;

// after
let token = match RegistrationToken::from_reader(File::open(&path)?) {
    Ok(token) => token,
    Err(TokenError::Read(source)) => {
        return Err(format!("cannot read registration token at {}: {source}", path.display()).into());
    }
    Err(other) => return Err(other.into()),
};

let meta = std::fs::metadata(&path)?; // surfaces NotFound/PermissionDenied with clear context
assert!(meta.is_file(), "registration token path must be a regular file");

match RegistrationToken::from_reader(reader) {
    Err(TokenError::Read(source)) => { /* classify via source.kind(); retry only after fixing path or permissions */ }
    Err(TokenError::Invalid(source)) => { /* log the serde error's field and offset */ }
    result => result,
}

When it happens

Trigger: RegistrationToken::from_reader(reader) where opening or reading fails: missing token file, permission denied, a directory in the file's place, or a stream that errors mid-read (broken pipe, early close).

Common situations: Wrong path in config (relative versus absolute, typo); token not yet provisioned or already rotated away; service user lacking read permission; reading from a pipe whose writer closed early.

Related errors

• Connect registration token configuration exceeds 16 KiB
• Connect heartbeat state I/O failed at {path}: {source}
• Connect registration token configuration is invalid
• Connect registration token secret must be 32-byte unpadded b
• RESPONSE_NOT_PRODUCED

AI-assisted analysis of rustfs/rustfs@201c653dcd (2026-08-23). Data as JSON: /api/errors/88841a34340cd1ed. Report an issue: GitHub.