clockworklabs/SpacetimeDB · error · anyhow::Error

version already exists

Error message

version already exists

What it means

The CLI version manager stores each installed version under its own bin directory. create_custom() links a custom binary into a version directory; if symlink_metadata shows a directory already exists at that path, it refuses to overwrite and bails.

Source

Thrown at crates/paths/src/cli.rs:82

                        entry.file_name().into_string().ok().map(Ok)
                    }
                }
                Err(e) => Some(Err(e.into())),
            })
            .collect()
    }
}

path_type!(VersionBinDir: dir);

impl VersionBinDir {
    pub fn spacetimedb_cli(self) -> SpacetimedbCliBin {
        SpacetimedbCliBin(self.0.joined("spacetimedb-cli").with_exe_ext())
    }

    pub fn create_custom(&self, path: &Path) -> anyhow::Result<()> {
        if std::fs::symlink_metadata(self).is_ok_and(|m| m.file_type().is_dir()) {
            anyhow::bail!("version already exists");
        }
        self.link_to(path)
    }

    fn link_to(&self, path: &Path) -> anyhow::Result<()> {
        let rel_path = path.strip_prefix(self.0.parent().unwrap()).unwrap_or(path);
        #[cfg(unix)]
        {
            // remove the link if it already exists
            std::fs::remove_file(self).ok();
            std::os::unix::fs::symlink(rel_path, self)?;
        }
        #[cfg(windows)]
        {
            junction::delete(self).ok();
            std::fs::remove_dir(self).ok();
            // We won't be able to create a junction if the fs isn't NTFS, so fall back to trying
            // to make a symlink.

View on GitHub (pinned to 6dee26c6ef)

Solutions

1. Uninstall the existing version first (spacetime version uninstall <version>, or remove the directory under the versions root).
2. Link the new build under a different, unique version label.
3. If the directory is stale debris from an interrupted install, delete it manually and re-run the link command.

Example fix

# before
spacetime-update link ./target/release/spacetimedb-cli v9.9.9-custom # -> version already exists

# after
spacetime version uninstall v9.9.9-custom
spacetime-update link ./target/release/spacetimedb-cli v9.9.9-custom

# before linking a custom version, check the target dir:
VERSIONS=$(spacetime data-dir)/versions  # adjust to your layout
[ -d "$VERSIONS/v9.9.9-custom/bin" ] && echo "exists -> uninstall first" || echo "safe to link"

match link_custom_version(&path, &label) {
    Err(e) if e.to_string() == "version already exists" => {
        uninstall_version(&label)?; // then retry the link once
        link_custom_version(&path, &label)
    }
    other => other,
}

When it happens

Trigger: Running the custom-version link subcommand (crates/update/src/cli/link.rs calls create_custom) for a version label whose bin directory already exists on disk.

Common situations: Re-linking a custom build under the same version label twice; leftover version directories after a failed or partial uninstall; switching between custom builds with identical labels.

Related errors

• could not serialize result: object had neither a `ok` nor an
• Tried to read ${n} byte(s) at relative offset ${this.offset}
• Module directory does not exist: '{}'. Check your --module-p
• Module bindings path must be a relative path
• Project initialization did not create spacetimedb directory

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/9bb337138b0659e5. Report an issue: GitHub.