clockworklabs/SpacetimeDB · error

initial publication requires a module and cannot require an…

Error message

initial publication requires a module and cannot require an existing version

What it means

publish_database in standalone distinguishes initial publication (no existing DB row) from update. An initial publish must carry a non-empty program (module bytes) and must not set expected_module_version, since there is no prior version to compare against. Otherwise anyhow::ensure! fails with this message and the publication is rejected.

Solutions

1. Include the compiled module program bytes in the publish spec for first publication.
2. Drop expected_module_version when the database does not exist yet (it only makes sense for updates).
3. If you intended an update, publish against the correct existing database identity instead of a new one.

Example fix

// before: update-style spec on a new database
spec.expected_module_version = Some(2); // DB doesn't exist -> error

// after: initial publish spec
let spec = PublishSpec { program_bytes: wasm, expected_module_version: None, .. }

function validatePublish(spec, exists) {
  if (!exists) {
    if (!spec.programBytes?.length) throw new Error('initial publish needs program bytes');
    if (spec.expectedModuleVersion != null) throw new Error('expected_module_version invalid on first publish');
  }
}

const isInitialSpec = (s) => !!s.program_bytes?.length && s.expected_module_version == null;

try { publish(spec); } catch (e) { if (e.message.includes('initial publication requires')) fixSpecForInitialPublish(); else throw e; }

When it happens

Trigger: Calling publish/`spacetime publish` for a brand-new database with empty program_bytes, or with expected_module_version set to some version despite the database not existing yet.

Common situations: A script reusing an 'update' payload (with expected_module_version) against a fresh database identity; publishing an empty or not-yet-built wasm file; CI template that always sets expected_module_version.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot use module-specific arguments
• Database ` ` does not exist
• database ownership changed before publication
• Either --out-dir or --uproject-dir is required
• Missing type name for

AI-assisted analysis of clockworklabs/SpacetimeDB@eddf9f5014 (2026-09-20). Data as JSON: /api/errors/65bdb1f7e0f35d42. Report an issue: GitHub.

Appendix: source

Thrown at crates/standalone/src/lib.rs:295

        publisher: &Identity,
        spec: spacetimedb_client_api::DatabaseDef,
        policy: MigrationPolicy,
    ) -> anyhow::Result<Option<UpdateDatabaseResult>> {
        let existing_db = self.control_db.get_database_by_identity(&spec.database_identity)?;

        let update = spacetimedb_lib::environment::EnvironmentUpdate {
            values: spec.environment,
            remove: spec.environment_remove,
            replace: spec.environment_replace,
        };
        update.validate()?;
        // standalone does not support replication.
        let num_replicas = 1;

        match existing_db {
            // The database does not already exist, so we'll create it.
            None => {
                anyhow::ensure!(
                    !spec.program_bytes.is_empty() && spec.expected_module_version.is_none(),
                    "initial publication requires a module and cannot require an existing version"
                );
                let environment = update.resulting_values(&Default::default())?;
                let program = Program::from_bytes(spec.host_type.into(), &spec.program_bytes[..]);

                let database = Database {
                    id: 0,
                    database_identity: spec.database_identity,
                    owner_identity: *publisher,
                    host_type: spec.host_type,
                    initial_program: program.hash,
                    bootstrap_generation: 0,
                };

                let _hash_for_assert = program.hash;

                // Instantiate a temporary database in order to check that the module is valid.

View on GitHub (pinned to eddf9f5014)