{"record":{"id":"d1d01651dd004db3","repo":"libnyanpasu/clash-nyanpasu","slug":"unsupported-migration-store-schema-version","errorCode":null,"errorMessage":"unsupported migration store schema version {}","messagePattern":"unsupported migration store schema version (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/tauri/src/core/migration/store.rs","lineNumber":66,"sourceCode":"            app: AppMigrationState::default(),\n            modules: BTreeMap::new(),\n            tasks: BTreeMap::new(),\n        }\n    }\n}\n\nimpl MigrationStore {\n    pub fn load(path: &Path) -> anyhow::Result<Self> {\n        if !path.exists() {\n            return Ok(Self::default());\n        }\n\n        let raw = std::fs::read_to_string(path)\n            .with_context(|| format!(\"failed to read migration state {}\", path.display()))?;\n        let store: Self = serde_yaml::from_str(&raw)\n            .with_context(|| format!(\"failed to parse migration state {}\", path.display()))?;\n        if store.store_schema_version != STORE_SCHEMA_VERSION {\n            bail!(\n                \"unsupported migration store schema version {}\",\n                store.store_schema_version\n            );\n        }\n        Ok(store)\n    }\n\n    pub fn flush_atomic(&self, path: &Path) -> anyhow::Result<()> {\n        let content = serde_yaml::to_string(self).context(\"failed to serialize migration state\")?;\n        let mut bytes =\n            b\"# This file is generated by the migration system, do not edit it manually.\\n\"\n                .to_vec();\n        bytes.extend_from_slice(content.as_bytes());\n        super::fs::atomic_write(path, &bytes).context(\"failed to persist migration state\")\n    }\n\n    pub fn task_state(&self, id: &str) -> Option<MigrationState> {\n        self.tasks.get(id).map(|task| task.state)","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/libnyanpasu/clash-nyanpasu/blob/f7dbce2997c633e484f54788035e770b3ee99773/backend/tauri/src/core/migration/store.rs#L48-L84","documentation":"Thrown by the migration store's `load` when the persisted migration state file declares a `store_schema_version` different from the version this build supports (`STORE_SCHEMA_VERSION`). The store is parsed successfully as YAML, but the code refuses to use it because the format cannot be trusted to match the current reader. This prevents silently misreading a state file written by a different application version.","triggerScenarios":"Calling `load` on a migration state file (read via `std::fs::read_to_string` and parsed with `serde_yaml`) whose `store_schema_version` field does not equal `STORE_SCHEMA_VERSION` — typically after upgrading or downgrading the app between releases that bumped the store schema.","commonSituations":"User upgrades the app while an old migration-state file from a previous schema version remains on disk; a downgrade or beta/nightly channel switch wrote a newer schema; the file was hand-edited or corrupted so the version field changed.","solutions":["Back up and delete the migration state file so the store is recreated with the current schema version on the next run.","Check the app changelog for a migration-notes entry about the schema bump and run any documented upgrade/conversion step before retrying.","If downgrading, use a state file matching the older `STORE_SCHEMA_VERSION` from a backup."],"exampleFix":"// before\n# migration-state.yaml\nstore_schema_version: 1\n...\n\n// after: remove the stale file so it is recreated with the current schema\nrm ~/.config/nyanpasu/migration-state.yaml\n// or, in code, migrate/rewrite:\nlet mut store = legacy_store; // parsed with old reader\nstore.store_schema_version = STORE_SCHEMA_VERSION;\nstore.save(&path)?;","handlingStrategy":"validation","validationCode":"// Verify the store schema version before loading\nuse serde::Deserialize;\n#[derive(Deserialize)]\nstruct VersionProbe { store_schema_version: u32 }\nlet probe: VersionProbe = serde_yaml::from_str(&raw)?;\nif probe.store_schema_version != STORE_SCHEMA_VERSION {\n    eprintln!(\"state file schema {} != supported {}; recreate or migrate it\",\n        probe.store_schema_version, STORE_SCHEMA_VERSION);\n}","typeGuard":null,"tryCatchPattern":"match store::load(&path) {\n    Err(e) if e.to_string().contains(\"unsupported migration store schema version\") => {\n        std::fs::rename(&path, path.with_extension(\"bak\"))?; // archive stale state\n        store::load_or_create(&path)?;\n    }\n    other => other?,\n}","preventionTips":["Back up the migration state file before upgrading the application","Read release notes for schema-version bumps and run shipped migration tooling","Avoid switching between stable and nightly channels sharing one config dir","Never hand-edit the store file, especially the version field"],"tags":["migration","schema","versioning","config"],"backgroundTag":"schema-validation-failed","analyzedSha":"f7dbce2997c633e484f54788035e770b3ee99773","analyzedAt":"2026-09-08T01:24:59.197Z","contentChangedAt":"2026-09-08T01:24:59.197Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}