pair-token store schema {schema_version} is newer than suppo

Error message

pair-token store schema {schema_version} is newer than supported schema {STORE_SCHEMA_VERSION}

What it means

The pair-token store carries a schema_version; if the on-disk file's version is greater than the STORE_SCHEMA_VERSION compiled into this build, load_from_disk refuses to parse it and returns InvalidData with both versions in the message. This prevents silently misreading a future format.

Source

Thrown at crates/astrid-kernel/src/pair_token/mod.rs:518

            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
            Err(e) => return Err(PairTokenStoreError::Io(e)),
        };
        let text = std::str::from_utf8(&bytes).map_err(|e| {
            PairTokenStoreError::Io(std::io::Error::new(std::io::ErrorKind::InvalidData, e))
        })?;
        if text.trim().is_empty() {
            if let Err(error) = self.save_to_disk(&[]) {
                warn!(
                    path = %self.path.display(),
                    %error,
                    "could not normalize empty pair-token store"
                );
            }
            return Ok(Vec::new());
        }
        let probe: SchemaProbe = toml::from_str(text).map_err(PairTokenStoreError::Toml)?;
        if probe.schema_version > STORE_SCHEMA_VERSION {
            return Err(PairTokenStoreError::Io(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                format!(
                    "pair-token store schema {} is newer than supported schema {STORE_SCHEMA_VERSION}",
                    probe.schema_version
                ),
            )));
        }
        let parsed: PersistedFile = toml::from_str(text).map_err(PairTokenStoreError::Toml)?;
        if probe.schema_version == 0 {
            let invalidated = parsed.pair_token.len();
            self.save_to_disk(&[])?;
            warn!(
                path = %self.path.display(),
                invalidated,
                "invalidated legacy SHA-256 pair-token store"
            );
            return Ok(Vec::new());
        }

View on GitHub (pinned to affd8760f4)

Solutions

Upgrade the application to a build whose STORE_SCHEMA_VERSION is >= the file's schema_version
Restore the store file from a backup made with the older schema
Delete the store file (re-pair tokens) if downgrade must proceed
Migrate manually by inspecting the newer format and rewriting it in the supported schema

Example fix

// before: downgrade without touching data
apt install app=1.2.0
// after: preserve/restore compatible store
cp pair-tokens.toml.bak-1.2 pair-tokens.toml && apt install app=1.2.0

Defensive patterns

Strategy: try-catch

Validate before calling

let text = std::fs::read_to_string(&store_path)?;
let probe: SchemaProbe = toml::from_str(&text)?;
if probe.schema_version > STORE_SCHEMA_VERSION { eprintln!("store schema too new: {}", probe.schema_version); }

Try / catch

match store.load() {
    Err(PairTokenStoreError::Io(e)) if e.to_string().contains("newer than supported schema") => {
        // upgrade binary or restore older-schema backup
    }
    other => other?,
}

Prevention

Back up the store before any version change
Avoid keeping new-format data directories across downgrades
Pin store schema version in deployment checks
Read release notes for schema bumps before upgrading

When it happens

Trigger: Calling PairTokenStore::load (→ load_from_disk) when the store file was written by a newer version of the software with a higher schema_version than the running binary supports.

Common situations: Downgraded the application binary while keeping the newer data directory; synced store files from a machine running a newer release; rolling-back deployment.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/169dfbef093e9e8f. Report an issue: GitHub.