{"record":{"id":"ca41fde86b26b3f1","repo":"clockworklabs/SpacetimeDB","slug":"database-addr-not-yet-initialized","errorCode":null,"errorMessage":"database `{addr}` not yet initialized","messagePattern":"database `(.+?)` not yet initialized","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/core/src/host/host_controller.rs","lineNumber":990,"sourceCode":"/// Update a module.\n///\n/// If the `db` is not initialized yet (i.e. its program hash is `None`),\n/// return an error.\n///\n/// Otherwise, if `db.program_hash` matches the given `program_hash`, do\n/// nothing and return an empty `UpdateDatabaseResult`.\n///\n/// Otherwise, invoke `module.update_database` and return the result.\nasync fn update_module(\n    db: &RelationalDB,\n    module: &ModuleHost,\n    program: Program,\n    old_module_info: Arc<ModuleInfo>,\n    policy: MigrationPolicy,\n) -> anyhow::Result<UpdateDatabaseResult> {\n    let addr = db.database_identity();\n    match stored_program_hash(db)? {\n        None => Err(anyhow!(\"database `{addr}` not yet initialized\")),\n        Some(stored) => {\n            let res = if stored == program.hash {\n                info!(\"database `{}` up to date with program `{}`\", addr, program.hash);\n                UpdateDatabaseResult::NoUpdateNeeded\n            } else {\n                info!(\"updating `{}` from {} to {}\", addr, stored, program.hash);\n                module.update_database(program, old_module_info, policy).await?\n            };\n\n            Ok(res)\n        }\n    }\n}\n\n/// Encapsulates a database, associated module, and auxiliary state.\nstruct Host {\n    /// The [`ModuleHost`], providing the callable reducer API.\n    ///","sourceCodeStart":972,"sourceCodeEnd":1008,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/core/src/host/host_controller.rs#L972-L1008","documentation":"update_module runs when a database update is requested (e.g. publishing a new module version) and looks up the stored program's hash to decide whether an update is needed. If no program was ever stored for this database there is nothing to update from, and it errors, naming the database's identity address.","triggerScenarios":"Publishing/updating against a database address that exists in the catalog but was never initialized with a module (created empty via API or tooling); internal update events targeting a not-yet-published database; a database left half-initialized after a failed publish.","commonSituations":"Addresses created out-of-band before first publish; crashed first publish leaving catalog rows without a program; retrying an update after a partially failed initial publish.","solutions":["Publish the module normally to initialize the database: `spacetime publish <db> --module-path <path>`.","Delete the half-created database and re-publish fresh.","If it recurs on a database you believe is initialized, capture server logs and report it — the stored program row is missing."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"const res = await fetch(`${server}/v1/database/${addr}/schema`, { headers: auth });\nif (res.status === 404) {\n  // no stored program yet — initialize with a full publish, not an update\n  await spacetimePublish(addr, modulePath);\n} else {\n  await spacetimePublishUpdate(addr, modulePath);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await publishUpdate(db);\n} catch (e) {\n  if (String(e).includes('not yet initialized')) {\n    return publishFresh(db); // fall back to initial publish\n  }\n  throw e;\n}","preventionTips":["Always complete the first `spacetime publish` before scripting update flows.","Treat a failed first publish as 'database absent' and republish cleanly.","Check for a stored schema before invoking update endpoints."],"tags":["spacetimedb","publish","database","initialization","module"],"backgroundTag":"database-not-initialized","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}