libnyanpasu/clash-nyanpasu · error

unsupported migration store schema version {}

Error message

unsupported migration store schema version {}

What it means

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.

Source

Thrown at backend/tauri/src/core/migration/store.rs:66

            app: AppMigrationState::default(),
            modules: BTreeMap::new(),
            tasks: BTreeMap::new(),
        }
    }
}

impl MigrationStore {
    pub fn load(path: &Path) -> anyhow::Result<Self> {
        if !path.exists() {
            return Ok(Self::default());
        }

        let raw = std::fs::read_to_string(path)
            .with_context(|| format!("failed to read migration state {}", path.display()))?;
        let store: Self = serde_yaml::from_str(&raw)
            .with_context(|| format!("failed to parse migration state {}", path.display()))?;
        if store.store_schema_version != STORE_SCHEMA_VERSION {
            bail!(
                "unsupported migration store schema version {}",
                store.store_schema_version
            );
        }
        Ok(store)
    }

    pub fn flush_atomic(&self, path: &Path) -> anyhow::Result<()> {
        let content = serde_yaml::to_string(self).context("failed to serialize migration state")?;
        let mut bytes =
            b"# This file is generated by the migration system, do not edit it manually.\n"
                .to_vec();
        bytes.extend_from_slice(content.as_bytes());
        super::fs::atomic_write(path, &bytes).context("failed to persist migration state")
    }

    pub fn task_state(&self, id: &str) -> Option<MigrationState> {
        self.tasks.get(id).map(|task| task.state)

View on GitHub (pinned to f7dbce2997)

Solutions

1. Back up and delete the migration state file so the store is recreated with the current schema version on the next run.
2. Check the app changelog for a migration-notes entry about the schema bump and run any documented upgrade/conversion step before retrying.
3. If downgrading, use a state file matching the older `STORE_SCHEMA_VERSION` from a backup.

Example fix

// before
# migration-state.yaml
store_schema_version: 1
...

// after: remove the stale file so it is recreated with the current schema
rm ~/.config/nyanpasu/migration-state.yaml
// or, in code, migrate/rewrite:
let mut store = legacy_store; // parsed with old reader
store.store_schema_version = STORE_SCHEMA_VERSION;
store.save(&path)?;

// Verify the store schema version before loading
use serde::Deserialize;
#[derive(Deserialize)]
struct VersionProbe { store_schema_version: u32 }
let probe: VersionProbe = serde_yaml::from_str(&raw)?;
if probe.store_schema_version != STORE_SCHEMA_VERSION {
    eprintln!("state file schema {} != supported {}; recreate or migrate it",
        probe.store_schema_version, STORE_SCHEMA_VERSION);
}

match store::load(&path) {
    Err(e) if e.to_string().contains("unsupported migration store schema version") => {
        std::fs::rename(&path, path.with_extension("bak"))?; // archive stale state
        store::load_or_create(&path)?;
    }
    other => other?,
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• unrecognized typed config migration state: existing {} is ne
• cannot repair typed clash config before split_legacy_config
• partial typed config migration state: existing [{}], missing
• profiles.yaml failed validation: {errors:?}
• clean-schema output rejected by domain model: {e}

AI-assisted analysis of libnyanpasu/clash-nyanpasu@f7dbce2997 (2026-09-08). Data as JSON: /api/errors/d1d01651dd004db3. Report an issue: GitHub.