{"record":{"id":"169dfbef093e9e8f","repo":"astrid-runtime/astrid","slug":"pair-token-store-schema-schema-version-is-newer","errorCode":null,"errorMessage":"pair-token store schema {schema_version} is newer than supported schema {STORE_SCHEMA_VERSION}","messagePattern":"pair-token store schema (.+?) is newer than supported schema (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-kernel/src/pair_token/mod.rs","lineNumber":518,"sourceCode":"            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),\n            Err(e) => return Err(PairTokenStoreError::Io(e)),\n        };\n        let text = std::str::from_utf8(&bytes).map_err(|e| {\n            PairTokenStoreError::Io(std::io::Error::new(std::io::ErrorKind::InvalidData, e))\n        })?;\n        if text.trim().is_empty() {\n            if let Err(error) = self.save_to_disk(&[]) {\n                warn!(\n                    path = %self.path.display(),\n                    %error,\n                    \"could not normalize empty pair-token store\"\n                );\n            }\n            return Ok(Vec::new());\n        }\n        let probe: SchemaProbe = toml::from_str(text).map_err(PairTokenStoreError::Toml)?;\n        if probe.schema_version > STORE_SCHEMA_VERSION {\n            return Err(PairTokenStoreError::Io(std::io::Error::new(\n                std::io::ErrorKind::InvalidData,\n                format!(\n                    \"pair-token store schema {} is newer than supported schema {STORE_SCHEMA_VERSION}\",\n                    probe.schema_version\n                ),\n            )));\n        }\n        let parsed: PersistedFile = toml::from_str(text).map_err(PairTokenStoreError::Toml)?;\n        if probe.schema_version == 0 {\n            let invalidated = parsed.pair_token.len();\n            self.save_to_disk(&[])?;\n            warn!(\n                path = %self.path.display(),\n                invalidated,\n                \"invalidated legacy SHA-256 pair-token store\"\n            );\n            return Ok(Vec::new());\n        }","sourceCodeStart":500,"sourceCodeEnd":536,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-kernel/src/pair_token/mod.rs#L500-L536","documentation":"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.","triggerScenarios":"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.","commonSituations":"Downgraded the application binary while keeping the newer data directory; synced store files from a machine running a newer release; rolling-back deployment.","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"],"exampleFix":"// before: downgrade without touching data\napt install app=1.2.0\n// after: preserve/restore compatible store\ncp pair-tokens.toml.bak-1.2 pair-tokens.toml && apt install app=1.2.0","handlingStrategy":"try-catch","validationCode":"let text = std::fs::read_to_string(&store_path)?;\nlet probe: SchemaProbe = toml::from_str(&text)?;\nif probe.schema_version > STORE_SCHEMA_VERSION { eprintln!(\"store schema too new: {}\", probe.schema_version); }","typeGuard":null,"tryCatchPattern":"match store.load() {\n    Err(PairTokenStoreError::Io(e)) if e.to_string().contains(\"newer than supported schema\") => {\n        // upgrade binary or restore older-schema backup\n    }\n    other => other?,\n}","preventionTips":["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"],"tags":["schema","versioning","backwards-compatibility"],"backgroundTag":"schema-version-mismatch","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}