atuinsh/atuin · error

unknown alias record version

Error message

unknown alias record version {other:?}

What it means

AliasRecord::deserialize first reads a version byte from the record payload. If that byte is not a version this decoder understands, it throws 'unknown alias record version'. This guards against decoding payloads whose wire format has changed.

Solutions

1. Upgrade atuin-dotfiles/atuin to the latest release so the new version byte is understood
2. Exclude or delete records with unknown versions from the local store
3. Pin all syncing machines to compatible atuin versions

Example fix

// before: fail on unknown version
let version = bytes[0];
// after: reject explicitly with a migration hint
let version = bytes[0];
if version > KNOWN_VERSION {
    return Err(eyre!("alias record version {version} requires atuin >= x.y; please upgrade"));
}

// Check the version byte before decoding
// fn is_supported_alias_version(payload: &[u8]) -> bool {
//     matches!(payload.first(), Some(&KNOWN_ALIAS_VERSION))
// }

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

match AliasRecord::deserialize(&mut bytes) {
    Ok(rec) => apply(rec),
    Err(e) if e.to_string().contains("unknown alias record version") => {
        log::warn!("alias record written by newer atuin; upgrade to read it");
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Deserializing an AliasRecord payload whose leading version byte differs from the versions compiled into this crate — e.g. data written by a newer atuin release with a bumped record format version.

Common situations: Downgraded or old atuin binary syncing records created by a newer version; mixing client versions across machines sharing a sync account.

Related errors

• unknown AliasRecord type
• unknown Dotfiles var record type
• unknown var record version
• too many entries in v0 dotfiles env create record, got
• trailing bytes in encoded dotfiles var record. malformed

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

Appendix: source

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

                        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 shell alias record. malformed");
                        }

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

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

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

impl AliasStore {
    // 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)