Precheck failed: added sequence {sequence_name} has invalid

Error message

Precheck failed: added sequence {sequence_name} has invalid min value

What it means

Auto-migrate precheck: converting the sequence's min value (sequence_def.min_value, defaulting to 1) into the sequenced column's type via saturating_value_from_i128 returned None, i.e. the min is not representable as that column's algebraic type — typically because the column is not an integer type at all.

Source

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

                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")
                })?;

                let range = min..=max;
                if stdb
                    .iter_by_col_range_mut(tx, table_id, sequence_def.column, range)?
                    .next()
                    .is_some()
                {
                    anyhow::bail!("Precheck failed: added sequence {sequence_name} already has values in range",);
                }

View on GitHub (pinned to 6dee26c6ef)

Solutions

Make the sequenced column an integer type wide enough for the declared min (e.g. u64/i64 identity columns)
Set an explicit min_value that fits the column type, or remove the custom min
Validate the module def (sequence column type vs min) before publishing

Example fix

// before: non-integer sequenced column
#[sequence(column = "name")]
struct T { name: String }

// after: integer identity column
#[sequence(column = "id")]
struct T { id: u64, name: String }

Defensive patterns

Strategy: validation

Validate before calling

// Check the sequenced column is an integer type that can hold the min
use spacetimedb_lib::AlgebraicType;
fn sequence_min_ok(col_ty: &AlgebraicType, min: i128) -> bool {
    col_ty.saturating_value_from_i128(min).is_some()
}

Type guard

fn is_integer_col(ty: &AlgebraicType) -> bool {
    matches!(t, AlgebraicType::U8 | AlgebraicType::U16 | AlgebraicType::U32
        | AlgebraicType::U64 | AlgebraicType::U128 | AlgebraicType::I8
        | AlgebraicType::I16 | AlgebraicType::I32 | AlgebraicType::I64 | AlgebraicType::I128)
}

Try / catch

match auto_migrate_database(&stdb, &mut tx, auth, &plan, &logger) {
    Err(e) if e.to_string().contains("invalid min value") => {
        anyhow::bail!("module error: {e:#}; use an integer sequence column or an explicit fitting min");
    }
    r => r,
}

Prevention

Only put sequences on integer identity columns (u64/i64)
Set explicit min/max only when they fit the column type
Validate sequence bounds in module lints before publish

When it happens

Trigger: Adding a sequence whose column's type cannot represent the min value (non-integer column, or an integer type that cannot hold the declared min); a module def declaring min_value below/above what the column type can represent where even saturation is not applicable.

Common situations: Putting a sequence attribute on a non-integer column in the module; widening/narrowing the sequenced column in the same publish that adds the sequence; hand-authored defs with unchecked min values.

Related errors

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