atuinsh/atuin · error

could not sync records due to version mismatch

Error message

could not sync records due to version mismatch

What it means

`record_status` fetches the remote record index from `api/v0/record` and calls `ensure_version` on the response before parsing it. If the response's version marker does not match what this client supports, it bails with this message. It protects the record store from syncing against a server protocol the client cannot interpret (or vice versa).

Solutions

1. Update the atuin CLI to the latest version (`atuin update` or your package manager)
2. If self-hosted, align server and client versions — upgrade both together
3. Check release notes for sync/record format changes between your versions
4. If you cannot upgrade, pin the server to a version compatible with your clients

Example fix

null

// Check version compatibility before syncing
let status = client.record_status().await; // if this fails, versions likely mismatch
// Or compare `atuin --version` against the server's supported versions

match client.record_status().await {
    Err(e) if e.to_string().contains("version mismatch") => {
        eprintln!("Update the atuin CLI to match the sync server's record format: {e}");
    }
    other => other,
}

When it happens

Trigger: A `record_status` call (used by sync flows like `atuin sync`) where the record index response fails `ensure_version` — server record format version differs from the client's expected version.

Common situations: Client and server atuin versions are out of sync (old client against a newer server or vice versa); a self-hosted server upgraded while clients were not; sync protocol v2 mismatches after upgrades.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• daemon sent a lag notice as a history event
• daemon sent an unspecified history tail event
• invalid id UUID format in sqlite DB
• {message}
• . Enable `daemon.autostart = true` or restart the daemon…

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

Appendix: source

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

    }

    /// Build a records request for `series`.
    pub fn records(&self, series: &RecordSeriesKey) -> RecordsRequest {
        RecordsRequest {
            client: self.clone(),
            series: series.clone(),
        }
    }

    #[instrument(level = "trace", skip_all, err)]
    pub async fn record_status(&self) -> Result<RecordStatus> {
        let url = self.sync_addr.append_path("api/v0/record")?;

        let resp = self.client.get(url).send().await?;
        let resp = handle_resp_error(resp).await?;

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

        let index = resp.json().await?;

        debug!("got remote index {index:?}");

        Ok(index)
    }

    #[instrument(level = "trace", skip_all, err)]
    pub async fn delete(&self) -> Result<()> {
        let url = self.sync_addr.append(["account"])?;

        let resp = self.client.delete(url).send().await?;

        if resp.status() == 403 {
            bail!("invalid login details");
        } else if resp.status() == 200 {

View on GitHub (pinned to 900007c480)