clockworklabs/SpacetimeDB · error · anyhow::Error

unable to lock database {} for migration planning

Error message

unable to lock database {} for migration planning

What it means

Planning a migration (the migrate-plan path that pretty-prints schema changes) first takes a per-replica read lock on the module host. Read-lock acquisition also has a 5-second timeout; when a writer (an in-progress publish/update or host initialization) holds the lock past that window, planning fails with this error naming the database identity.

Source

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

    pub async fn migrate_plan(
        &self,
        database: Database,
        host_type: HostType,
        replica_id: u64,
        program_bytes: Box<[u8]>,
        style: PrettyPrintStyle,
    ) -> anyhow::Result<MigratePlanResult> {
        let program = Program::from_bytes(host_type.into(), program_bytes);
        trace!(
            "migrate plan {}/{}: genesis={} update-to={}",
            database.database_identity,
            replica_id,
            database.initial_program,
            program.hash
        );

        let Ok(guard) = self.acquire_read_lock(replica_id).await else {
            bail!(
                "unable to lock database {} for migration planning",
                database.database_identity
            );
        };
        let host = guard.as_ref().ok_or(NoSuchModule)?;

        host.migrate_plan(
            self.page_pool.clone(),
            self.bsatn_rlb_pool.clone(),
            &self.runtimes,
            host_type,
            program,
            style,
        )
        .await
    }

    /// Release all resources of the [`ModuleHost`] identified by `replica_id`,

View on GitHub (pinned to fdd647dfac)

Solutions

1. Retry the migrate plan after the concurrent publish/update completes
2. Check server logs to identify the writer holding the replica lock
3. Restart the node if no operation is legitimately in flight yet the lock never frees
4. Sequence 'plan then apply' migrations in tooling so they don't race deploys

# shell: retry migration planning after concurrent writes finish
for i in 1 2 3; do
  spacetime migrate plan my-db --project-path . && exit 0
  echo "attempt $i: replica lock busy during planning" >&2
  sleep 10
done
exit 1

When it happens

Trigger: Running `spacetime migrate plan` (or anything invoking migrate_plan) while a publish/update of the same database holds the write lock for more than 5 seconds; or a stuck holder blocking all lockers.

Common situations: Planning a migration while a CI deploy is publishing; a long-running update initialization overlapping the plan request; retrying a plan right after cancelling an update whose tasks still hold the lock.

Related errors

• unable to lock database {} for initialization
• unable to lock database {} for update
• When providing a name, you must also provide the variants ob
• Precheck failed: added sequence {sequence_name} already has
• Cannot remove table `{table_name}`: table contains data. Cle

AI-assisted analysis of clockworklabs/SpacetimeDB@fdd647dfac (2026-08-20). Data as JSON: /api/errors/98cd2da4f49a1be6. Report an issue: GitHub.