{"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/c0c717ab04c881764bcad4b3d169a507e2432643/crates/atuin-client/src/api_client.rs#L136-L172","documentation":"After posting to `/register`, the client calls `ensure_version`, which compares the server's reported version against the client's. If the server version header is missing/too old (version negotiation fails), registration is aborted with this message because old servers cannot support the current registration flow.","triggerScenarios":"`atuin register` against a sync server whose `x-atuin-version` header indicates an incompatible (older) major version, or whose version cannot be validated by `ensure_version`","commonSituations":"Self-hosted server not upgraded after a breaking client release; running an old atuin-server docker image while the CLI is current","solutions":["Upgrade the sync server to a version matching or exceeding the client","Check the server version header is being emitted (reverse proxy stripping headers?)","Downgrade the client if you must keep the old server (not recommended)"],"exampleFix":"// before\ndocker run ghcr.io/atuinsh/atuin:v17 server start\n// after\ndocker pull ghcr.io/atuinsh/atuin:latest && docker run ghcr.io/atuinsh/atuin:latest server start","handlingStrategy":"validation","validationCode":"// check server version before registering\nlet resp = client.get(format!(\"{address}/health\")).send().await?;\nlet server_ver = resp.headers().get(\"x-atuin-version\")\n    .and_then(|v| v.to_str().ok())\n    .ok_or_else(|| eyre!(\"server missing version header\"))?;\nif Version::parse(server_ver)?.major < ATUIN_VERSION.major {\n    eprintln!(\"upgrade the sync 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 atuin sync server, then retry\");\n    }\n    other => other?,\n}","preventionTips":["Keep atuin-server and CLI versions in lockstep","After upgrading the CLI, upgrade the server before syncing","Verify the version header survives your reverse proxy"],"tags":["version-mismatch","sync","registration"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"c0c717ab04c881764bcad4b3d169a507e2432643","analyzedAt":"2026-09-12T07:40:01.341Z","contentChangedAt":"2026-09-12T07:40:01.341Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}