clockworklabs/SpacetimeDB · critical

metadata.toml indicates that you are running {relation} data

Error message

metadata.toml indicates that you are running {relation} database. Your running version is {:?}, but the database on disk is from {:?}.

What it means

After the edition check, the versions in metadata.toml are compared with a caret-style semver range: a database may only be opened by a compatible server version. This error fires when the running binary's version does not satisfy that range, and the message states whether the on-disk database is from a newer, older, or otherwise incompatible version than the running one.

Source

Thrown at crates/core/src/config.rs:106

            major: previous.version.major,
            minor: Some(previous.version.minor),
            patch: None,
            // We deal with pre-releases separately above.
            pre: semver::Prerelease::new("").unwrap(),
        };

        if cmp.matches(&current.version) {
            return Ok(());
        }

        let relation = if previous.version > current.version {
            "a newer, incompatible"
        } else if previous.version < current.version {
            "an older, incompatible"
        } else {
            "an incompatible"
        };
        anyhow::bail!(
            "metadata.toml indicates that you are running {relation} database. Your running version is {:?}, but the database on disk is from {:?}.",
            current.version,
            previous.version,
        );
    }

    /// Check if this meta file is compatible with the default meta
    /// file of a just-started database, and if so return the metadata
    /// to write back to the file.
    ///
    /// `self` is the metadata file read from a database, and current is
    /// the default metadata file that the active database version would
    /// right to a new database.
    pub fn check_compatibility_and_update(mut self, current: Self, metafile: &Path) -> anyhow::Result<Self> {
        Self::check_compatibility(&self, &current, metafile)?;
        // bump the version in the file only if it's being run in a newer database.
        self.version = std::cmp::max(self.version, current.version);
        Ok(self)

View on GitHub (pinned to 524b4487d9)

Solutions

1. Upgrade the node to a version compatible with the database (the safe direction is always upward).
2. Read the exact version from <data-dir>/<db>/metadata.toml and run that version or newer.
3. If rollback is mandatory and the data is disposable, delete the database directory and re-publish.
4. Back up the data directory before any version change.

#!/usr/bin/env bash
META="$DATA_DIR/<database>/metadata.toml"
db_version=$(grep -oP 'version\s*=\s*"\K[^"]+' "$META")
# refuse to start if the binary cannot safely open this data dir
python3 - "$db_version" "$BINARY_VERSION" <<'EOF'
import sys
from packaging.version import Version
db, cur = Version(sys.argv[1]), Version(sys.argv[2])
if cur < db:
    sys.exit(f'downgrade refused: data dir is {db}, binary is {cur}')
EOF
exec spacetime start --data-dir "$DATA_DIR"

When it happens

Trigger: Downgrading the SpacetimeDB binary below the version that last wrote the database; upgrading across a breaking (major) version boundary; opening a database written by a newer minor release whose changes fall outside the caret range.

Common situations: Rolling back a container image after an upgrade while keeping the data volume; restoring newer backups onto older deployments; CI pinning an old version against persistent data directories.

Related errors

• metadata.toml at {} indicates that this database is from a d
• Unsupported UUID version: ${version}
• Manual database migrations are not yet implemented
• Multiple databases found in config: {}. Please specify which
• Database '{}' is not in the config file. If you want to run

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/6397a032ef2c382c. Report an issue: GitHub.