clockworklabs/SpacetimeDB · critical

metadata.toml at {} indicates that this database is from a d

Error message

metadata.toml at {} indicates that this database is from a different edition of SpacetimeDB (running {:?}, but this database is {:?})

What it means

Every database records an edition field in its metadata.toml; on open, the node compares it with the running build's edition and refuses to proceed when they differ. This guards against reading on-disk state written by a different edition of SpacetimeDB, whose storage formats are not interchangeable.

Source

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

            current_version.patch = 0;
        }
        Self {
            version: current_version,
            edition: edition.to_owned(),
            client_connection_id: None,
        }
    }

    pub fn read(path: &MetadataTomlPath) -> anyhow::Result<Option<Self>> {
        parse_config(path.as_ref())
    }

    pub fn write(&self, path: &MetadataTomlPath) -> io::Result<()> {
        path.write(self.to_string())
    }

    fn check_compatibility(previous: &Self, current: &Self, metafile: &Path) -> anyhow::Result<()> {
        anyhow::ensure!(
            previous.edition == current.edition,
            "metadata.toml at {} indicates that this database is from a different \
            edition of SpacetimeDB (running {:?}, but this database is {:?})",
            metafile.display(),
            current.edition,
            previous.edition,
        );

        // This is mostly redundant with the caret comparison below, but
        // pre-releases make it annoying.
        if previous.version == current.version {
            return Ok(());
        }

        // Special-case: SpacetimeDB 2.x can run 1.x databases.
        if previous.version.major == 1 && current.version.major == 2 {
            return Ok(());
        }

View on GitHub (pinned to 524b4487d9)

Solutions

1. Run the same edition that created the database — read the edition value from <data-dir>/<db>/metadata.toml.
2. Re-publish the module into a fresh database created by the current edition.
3. If the data is disposable, delete the database directory and start clean.
4. Contact SpacetimeDB support if the on-disk data must be migrated across editions.

#!/usr/bin/env bash
# before starting a server against an existing data dir
META="$DATA_DIR/<database>/metadata.toml"
if [ -f "$META" ]; then
  db_edition=$(grep -oP 'edition\s*=\s*"\K[^"]+' "$META")
  [ "$db_edition" = "$RUNNING_EDITION" ] || { echo "data dir is edition '$db_edition', binary is '$RUNNING_EDITION'" >&2; exit 1; }
fi
exec spacetime start --data-dir "$DATA_DIR"

When it happens

Trigger: Pointing a server binary built for one edition at a data directory created by another edition; restoring a backup taken from a deployment running a different edition; switching container images across editions while keeping the data volume.

Common situations: Mixing binaries or images from different distributions; copying data dirs between environments; edition identifiers changing between versions of the product.

Related errors

• metadata.toml indicates that you are running {relation} data
• 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
• the following required arguments were not provided: <datab

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