Precheck failed: added sequence {sequence_name} refers to un

Error message

Precheck failed: added sequence {sequence_name} refers to unknown column

What it means

Auto-migrate precheck: an added sequence references a column via sequence_def.column that table_def.get_column cannot find in the new storing table's definition. The sequence points at a column that does not exist in the table it is stored on.

Source

Thrown at crates/engine/src/update.rs:231

    // to later steps.

    for precheck in plan.prechecks {
        match precheck {
            spacetimedb_schema::auto_migrate::AutoMigratePrecheck::CheckAddSequenceRangeValid(key) => {
                let (namespace, sequence_name) = key;
                let (_, table_def) = plan.new.find_storing_table(namespace, sequence_name).ok_or_else(|| {
                    anyhow::anyhow!("Precheck: sequence `{sequence_name}` not found in new module def")
                })?;
                let sequence_def: &SequenceDef = plan.new.lookup(key).ok_or_else(|| {
                    anyhow::anyhow!("Precheck: sequence `{sequence_name}` not found in new module def")
                })?;
                let table_full_name = joined(namespace, &table_def.name);
                let table_id = stdb.table_id_from_name_mut(tx, &table_full_name)?.unwrap();

                let ty = table_def
                    .get_column(sequence_def.column)
                    .ok_or_else(|| {
                        anyhow::anyhow!("Precheck failed: added sequence {sequence_name} refers to unknown column")
                    })?
                    .ty
                    .clone();

                // Convert `SequenceDef` min/max to `AlgebraicValue`s of the correct type.
                let min = ty
                    .saturating_value_from_i128(sequence_def.min_value.unwrap_or(1))
                    .ok_or_else(|| {
                        anyhow::anyhow!("Precheck failed: added sequence {sequence_name} has invalid min value")
                    })?;

                let max = match sequence_def.max_value {
                    Some(max) => ty.saturating_value_from_i128(max),
                    None => ty.saturating_value_from_i128(i128::MAX),
                }
                .ok_or_else(|| {
                    anyhow::anyhow!("Precheck failed: added sequence {sequence_name} has invalid max value")
                })?;

View on GitHub (pinned to 6dee26c6ef)

Solutions

Fix the module so the sequence's column exists in the new table def (keep names in sync)
If renaming was intended, update the sequence definition to the new column name and re-publish
Report upstream if the defs are consistent and the differ still produced the dangling reference

Example fix

// module (before): sequence refers to a removed/renamed column
#[sequence(column = "id_old")]
struct MyTable { id_new: u64, ... }

// after: column name matches
#[sequence(column = "id_new")]
struct MyTable { id_new: u64, ... }

Defensive patterns

Strategy: validation

Validate before calling

// Module authors: verify the sequence's column exists before publishing
let col = table_def.get_column(sequence_def.column);
anyhow::ensure!(col.is_some(),
    "sequence {} refers to missing column {}", sequence_name, sequence_def.column);

Type guard

fn sequence_column_exists(t: &TableDef, seq: &SequenceDef) -> bool {
    t.get_column(seq.column).is_some()
}

Try / catch

match auto_migrate_database(&stdb, &mut tx, auth, &plan, &logger) {
    Err(e) if e.to_string().contains("refers to unknown column") => {
        // fix the module def (column name) and republish; retrying unchanged will fail again
        anyhow::bail!("module error: {e:#}");
    }
    r => r,
}

Prevention

Keep sequence column attributes synchronized with column renames
Run module validation before publish
Prefer derives/macros over hand-written SequenceDefs

When it happens

Trigger: A publish that renames or removes a column while also adding a sequence on it, with the diff not pairing the changes; a hand-written SequenceDef with a stale column name; upstream differ bug emitting a sequence before its column exists.

Common situations: Renaming an auto-inc column in the same module version that introduces a sequence; editing generated module defs by hand; version skew in the schema crate.

Related errors

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/36bd5dffd6250588. Report an issue: GitHub.