atuinsh/atuin · error

could not register user due to version mismatch

Error message

could not register user due to version mismatch

What it means

After posting to `/register`, `ensure_version` compares the server's reported version with the client's. Registration is aborted when versions are incompatible (client newer than the server can handle, or the check fails), so the account is not created.

Solutions

1. Upgrade the sync server (`atuin server` container/binary) to match or exceed the client version
2. Downgrade or pin the client to a release compatible with your server
3. Check both versions with `atuin --version` and compare
4. On self-hosted setups, pin client and server to the same release

// compare versions before registering
let client_ver = atuin_common::utils::VERSION;
let server_ver = fetch_server_version(&address).await?;
if semver::Version::parse(&server_ver)? < semver::Version::parse(client_ver)? {
    eprintln!("upgrade the server before registering");
    return Ok(());
}

match register(...).await {
    Err(e) if e.to_string().contains("version mismatch") => {
        eprintln!("upgrade your sync server, then retry");
        Err(e)
    }
    other => other,
}

When it happens

Trigger: Registering against a sync server whose `x-atuin-version` header indicates it is older than required for current registration payloads.

Common situations: Self-hosted server not upgraded alongside a bleeding-edge client; mixing release channels (main-branch client vs stable server).

Related errors

• Could not login due to version mismatch
• failed to parse server version
• Hub registration failed with status
• {message}
• Server not reporting its version: it is either too old or…

AI-assisted analysis of atuinsh/atuin@900007c480 (2026-09-19). Data as JSON: /api/errors/745e553b692735ba. Report an issue: GitHub.

Appendix: source

Thrown at crates/atuin-client/src/api_client.rs:154

    let mut headers = extra_headers_map(extra_headers)?;
    headers.insert(USER_AGENT, APP_USER_AGENT.parse()?);
    headers.insert(ATUIN_HEADER_VERSION, ATUIN_CARGO_VERSION.parse()?);

    let client = client_builder(extra_headers).build()?;

    let url = address.append(["user", username])?;
    let resp = client.get(url).headers(headers.clone()).send().await?;

    if resp.status().is_success() {
        bail!("username already in use");
    }

    let url = address.append(["register"])?;
    let resp = client.post(url).headers(headers).json(&map).send().await?;
    let resp = handle_resp_error(resp).await?;

    if !ensure_version(&resp)? {
        bail!("could not register user due to version mismatch");
    }

    let session = resp.json::<RegisterResponse>().await?;
    Ok(session)
}

#[instrument(level = "trace", skip_all, err)]
pub async fn login(
    address: &Url,
    req: LoginRequest,
    extra_headers: &HashMap<String, String>,
) -> Result<LoginResponse> {
    let url = address.append(["login"])?;
    let client = client_builder(extra_headers).build()?;

    let mut headers = extra_headers_map(extra_headers)?;
    headers.insert(USER_AGENT, APP_USER_AGENT.parse()?);

View on GitHub (pinned to 900007c480)