What causes "unknown var record version {other:?}" in atuinsh/atuin?

Upgrade atuin so the record version is supported

unknown var record version

Error message

unknown var record version {other:?}

What it means

The var record decoder reads a leading version byte and only implements the versions it knows. Any other version byte triggers 'unknown var record version'. This prevents misinterpreting a payload whose wire format differs.

Solutions

Upgrade atuin so the record version is supported
Skip/ignore unknown-version records during sync
Re-create the dotfiles data with the current atuin version

Defensive patterns

Strategy: try-catch

Validate before calling

// Check the version byte of the var record payload
// fn is_supported_var_version(payload: &[u8]) -> bool {
//     payload.first() == Some(&VAR_KNOWN_VERSION)
// }

Type guard

fn is_supported_var_version(payload: &[u8]) -> bool {
    payload.first() == Some(&VAR_KNOWN_VERSION)
}

Try / catch

match VarRecord::deserialize(&mut bytes) {
    Ok(rec) => apply(rec),
    Err(e) if e.to_string().contains("unknown var record version") => {
        log::warn!("var record format version unsupported; upgrade atuin");
    }
    Err(e) => return Err(e),
}

Prevention

Avoid running older atuin clients against records written by newer ones
Confirm format version bumps in release notes before upgrades/downgrades
Re-export dotfiles data if restoring from a mixed-version backup

When it happens

Trigger: Deserializing a var record payload written with a format version not present in this build — typically newer-format records synced to an older client.

Common situations: Version skew between machines syncing the same atuin account; restoring an old backup against newer records.

Related errors

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

Appendix: source

Thrown at crates/atuin-dotfiles/src/store/var.rs:90

                        let bytes = bytes.remaining_slice();

                        let (key, bytes) =
                            decode::read_str_from_slice(bytes).map_err(error_report)?;

                        if !bytes.is_empty() {
                            bail!("trailing bytes in encoded dotfiles var record. malformed");
                        }

                        Ok(Self::Delete(key.to_owned()))
                    }

                    n => {
                        bail!("unknown Dotfiles var record type {n}");
                    }
                }
            }
            other => {
                bail!("unknown var record version {other:?}");
            }
        }
    }
}

#[derive(Debug, Clone)]
pub struct VarStore {
    pub store: SqliteStore,
    pub host_id: HostId,
    pub encryption_key: paseto_v4::Key,
}

impl VarStore {
    // will want to init the actual kv store when that is done
    #[must_use]
    pub fn new(store: SqliteStore, host_id: HostId, encryption_key: paseto_v4::Key) -> Self {
        Self {
            store,

View on GitHub (pinned to 900007c480)