{"record":{"id":"6397a032ef2c382c","repo":"clockworklabs/SpacetimeDB","slug":"metadata-toml-indicates-that-you-are-running-rela","errorCode":null,"errorMessage":"metadata.toml indicates that you are running {relation} database. Your running version is {:?}, but the database on disk is from {:?}.","messagePattern":"metadata\\.toml indicates that you are running (.+?) database\\. Your running version is (.+?), but the database on disk is from (.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/core/src/config.rs","lineNumber":106,"sourceCode":"            major: previous.version.major,\n            minor: Some(previous.version.minor),\n            patch: None,\n            // We deal with pre-releases separately above.\n            pre: semver::Prerelease::new(\"\").unwrap(),\n        };\n\n        if cmp.matches(&current.version) {\n            return Ok(());\n        }\n\n        let relation = if previous.version > current.version {\n            \"a newer, incompatible\"\n        } else if previous.version < current.version {\n            \"an older, incompatible\"\n        } else {\n            \"an incompatible\"\n        };\n        anyhow::bail!(\n            \"metadata.toml indicates that you are running {relation} database. Your running version is {:?}, but the database on disk is from {:?}.\",\n            current.version,\n            previous.version,\n        );\n    }\n\n    /// Check if this meta file is compatible with the default meta\n    /// file of a just-started database, and if so return the metadata\n    /// to write back to the file.\n    ///\n    /// `self` is the metadata file read from a database, and current is\n    /// the default metadata file that the active database version would\n    /// right to a new database.\n    pub fn check_compatibility_and_update(mut self, current: Self, metafile: &Path) -> anyhow::Result<Self> {\n        Self::check_compatibility(&self, &current, metafile)?;\n        // bump the version in the file only if it's being run in a newer database.\n        self.version = std::cmp::max(self.version, current.version);\n        Ok(self)","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/core/src/config.rs#L88-L124","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the node to a version compatible with the database (the safe direction is always upward).","Read the exact version from <data-dir>/<db>/metadata.toml and run that version or newer.","If rollback is mandatory and the data is disposable, delete the database directory and re-publish.","Back up the data directory before any version change."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"#!/usr/bin/env bash\nMETA=\"$DATA_DIR/<database>/metadata.toml\"\ndb_version=$(grep -oP 'version\\s*=\\s*\"\\K[^\"]+' \"$META\")\n# refuse to start if the binary cannot safely open this data dir\npython3 - \"$db_version\" \"$BINARY_VERSION\" <<'EOF'\nimport sys\nfrom packaging.version import Version\ndb, cur = Version(sys.argv[1]), Version(sys.argv[2])\nif cur < db:\n    sys.exit(f'downgrade refused: data dir is {db}, binary is {cur}')\nEOF\nexec spacetime start --data-dir \"$DATA_DIR\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only upgrade servers against existing data dirs; never downgrade.","Back up the data directory before every version change.","Read metadata.toml version as a pre-deploy assertion in CI."],"tags":["spacetimedb","metadata","version","semver","database","compatibility"],"backgroundTag":"database-version-mismatch","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}