{"record":{"id":"65bdb1f7e0f35d42","repo":"clockworklabs/SpacetimeDB","slug":"initial-publication-requires-a-module-and-cannot-require-an","errorCode":null,"errorMessage":"initial publication requires a module and cannot require an existing version","messagePattern":"initial publication requires a module and cannot require an existing version","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/standalone/src/lib.rs","lineNumber":295,"sourceCode":"        publisher: &Identity,\n        spec: spacetimedb_client_api::DatabaseDef,\n        policy: MigrationPolicy,\n    ) -> anyhow::Result<Option<UpdateDatabaseResult>> {\n        let existing_db = self.control_db.get_database_by_identity(&spec.database_identity)?;\n\n        let update = spacetimedb_lib::environment::EnvironmentUpdate {\n            values: spec.environment,\n            remove: spec.environment_remove,\n            replace: spec.environment_replace,\n        };\n        update.validate()?;\n        // standalone does not support replication.\n        let num_replicas = 1;\n\n        match existing_db {\n            // The database does not already exist, so we'll create it.\n            None => {\n                anyhow::ensure!(\n                    !spec.program_bytes.is_empty() && spec.expected_module_version.is_none(),\n                    \"initial publication requires a module and cannot require an existing version\"\n                );\n                let environment = update.resulting_values(&Default::default())?;\n                let program = Program::from_bytes(spec.host_type.into(), &spec.program_bytes[..]);\n\n                let database = Database {\n                    id: 0,\n                    database_identity: spec.database_identity,\n                    owner_identity: *publisher,\n                    host_type: spec.host_type,\n                    initial_program: program.hash,\n                    bootstrap_generation: 0,\n                };\n\n                let _hash_for_assert = program.hash;\n\n                // Instantiate a temporary database in order to check that the module is valid.","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/eddf9f5014579a50d4b67630e28b6e15cad9c4af/crates/standalone/src/lib.rs#L277-L313","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Include the compiled module program bytes in the publish spec for first publication.","Drop expected_module_version when the database does not exist yet (it only makes sense for updates).","If you intended an update, publish against the correct existing database identity instead of a new one."],"exampleFix":"// before: update-style spec on a new database\nspec.expected_module_version = Some(2); // DB doesn't exist -> error\n\n// after: initial publish spec\nlet spec = PublishSpec { program_bytes: wasm, expected_module_version: None, .. }","handlingStrategy":"validation","validationCode":"function validatePublish(spec, exists) {\n  if (!exists) {\n    if (!spec.programBytes?.length) throw new Error('initial publish needs program bytes');\n    if (spec.expectedModuleVersion != null) throw new Error('expected_module_version invalid on first publish');\n  }\n}","typeGuard":"const isInitialSpec = (s) => !!s.program_bytes?.length && s.expected_module_version == null;","tryCatchPattern":"try { publish(spec); } catch (e) { if (e.message.includes('initial publication requires')) fixSpecForInitialPublish(); else throw e; }","preventionTips":["Only set expected_module_version for updates to existing databases","Ensure wasm builds are complete before publishing","Check database existence before choosing initial vs update spec"],"tags":["publish","validation","standalone","arguments"],"backgroundTag":"invalid-argument-value","analyzedSha":"eddf9f5014579a50d4b67630e28b6e15cad9c4af","analyzedAt":"2026-09-20T12:15:59.611Z","contentChangedAt":"2026-09-20T12:15:59.611Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}