clockworklabs/SpacetimeDB · error

database `{addr}` not yet initialized

Error message

database `{addr}` not yet initialized

What it means

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.

Source

Thrown at crates/core/src/host/host_controller.rs:990

/// Update a module.
///
/// If the `db` is not initialized yet (i.e. its program hash is `None`),
/// return an error.
///
/// Otherwise, if `db.program_hash` matches the given `program_hash`, do
/// nothing and return an empty `UpdateDatabaseResult`.
///
/// Otherwise, invoke `module.update_database` and return the result.
async fn update_module(
    db: &RelationalDB,
    module: &ModuleHost,
    program: Program,
    old_module_info: Arc<ModuleInfo>,
    policy: MigrationPolicy,
) -> anyhow::Result<UpdateDatabaseResult> {
    let addr = db.database_identity();
    match stored_program_hash(db)? {
        None => Err(anyhow!("database `{addr}` not yet initialized")),
        Some(stored) => {
            let res = if stored == program.hash {
                info!("database `{}` up to date with program `{}`", addr, program.hash);
                UpdateDatabaseResult::NoUpdateNeeded
            } else {
                info!("updating `{}` from {} to {}", addr, stored, program.hash);
                module.update_database(program, old_module_info, policy).await?
            };

            Ok(res)
        }
    }
}

/// Encapsulates a database, associated module, and auxiliary state.
struct Host {
    /// The [`ModuleHost`], providing the callable reducer API.
    ///

View on GitHub (pinned to 524b4487d9)

Solutions

1. Publish the module normally to initialize the database: `spacetime publish <db> --module-path <path>`.
2. Delete the half-created database and re-publish fresh.
3. If it recurs on a database you believe is initialized, capture server logs and report it — the stored program row is missing.

const res = await fetch(`${server}/v1/database/${addr}/schema`, { headers: auth });
if (res.status === 404) {
  // no stored program yet — initialize with a full publish, not an update
  await spacetimePublish(addr, modulePath);
} else {
  await spacetimePublishUpdate(addr, modulePath);
}

try {
  await publishUpdate(db);
} catch (e) {
  if (String(e).includes('not yet initialized')) {
    return publishFresh(db); // fall back to initial publish
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Manual database migrations are not yet implemented
• Could not find a SpacetimeDB module in spacetimedb/ or the c
• Multiple databases found in config: {}. Please specify which
• Database '{}' is not in the config file. If you want to run
• the following required arguments were not provided: <datab

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/ca41fde86b26b3f1. Report an issue: GitHub.