{"record":{"id":"745e553b692735ba","repo":"atuinsh/atuin","slug":"could-not-register-user-due-to-version-mismatch","errorCode":null,"errorMessage":"could not register user due to version mismatch","messagePattern":"could not register user due to version mismatch","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/atuin-client/src/api_client.rs","lineNumber":154,"sourceCode":"    let mut headers = extra_headers_map(extra_headers)?;\n    headers.insert(USER_AGENT, APP_USER_AGENT.parse()?);\n    headers.insert(ATUIN_HEADER_VERSION, ATUIN_CARGO_VERSION.parse()?);\n\n    let client = client_builder(extra_headers).build()?;\n\n    let url = address.append([\"user\", username])?;\n    let resp = client.get(url).headers(headers.clone()).send().await?;\n\n    if resp.status().is_success() {\n        bail!(\"username already in use\");\n    }\n\n    let url = address.append([\"register\"])?;\n    let resp = client.post(url).headers(headers).json(&map).send().await?;\n    let resp = handle_resp_error(resp).await?;\n\n    if !ensure_version(&resp)? {\n        bail!(\"could not register user due to version mismatch\");\n    }\n\n    let session = resp.json::<RegisterResponse>().await?;\n    Ok(session)\n}\n\n#[instrument(level = \"trace\", skip_all, err)]\npub async fn login(\n    address: &Url,\n    req: LoginRequest,\n    extra_headers: &HashMap<String, String>,\n) -> Result<LoginResponse> {\n    let url = address.append([\"login\"])?;\n    let client = client_builder(extra_headers).build()?;\n\n    let mut headers = extra_headers_map(extra_headers)?;\n    headers.insert(USER_AGENT, APP_USER_AGENT.parse()?);\n","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/atuinsh/atuin/blob/900007c48045867e7f44b0f9bc55ad9dbe99ee0d/crates/atuin-client/src/api_client.rs#L136-L172","documentation":"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.","triggerScenarios":"Registering against a sync server whose `x-atuin-version` header indicates it is older than required for current registration payloads.","commonSituations":"Self-hosted server not upgraded alongside a bleeding-edge client; mixing release channels (main-branch client vs stable server).","solutions":["Upgrade the sync server (`atuin server` container/binary) to match or exceed the client version","Downgrade or pin the client to a release compatible with your server","Check both versions with `atuin --version` and compare","On self-hosted setups, pin client and server to the same release"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// compare versions before registering\nlet client_ver = atuin_common::utils::VERSION;\nlet server_ver = fetch_server_version(&address).await?;\nif semver::Version::parse(&server_ver)? < semver::Version::parse(client_ver)? {\n    eprintln!(\"upgrade the server before registering\");\n    return Ok(());\n}","typeGuard":null,"tryCatchPattern":"match register(...).await {\n    Err(e) if e.to_string().contains(\"version mismatch\") => {\n        eprintln!(\"upgrade your sync server, then retry\");\n        Err(e)\n    }\n    other => other,\n}","preventionTips":["Keep server and client on the same release channel","Check `atuin --version` on both ends before upgrades","Pin container images to matching versions"],"tags":["versioning","registration","compatibility"],"backgroundTag":"api-error-response","analyzedSha":"900007c48045867e7f44b0f9bc55ad9dbe99ee0d","analyzedAt":"2026-09-19T12:52:51.491Z","contentChangedAt":"2026-09-19T12:52:51.491Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}