Invalid sequence: increment must be less than or equal to th

Error message

Invalid sequence: increment must be less than or equal to the range between min_value and max_value

What it means

Fourth invariant in Sequence::new: increment.unsigned_abs() must be strictly less than (max_value - min_value) computed as u128 — the check panics on `>=`. (The message text says 'less than or equal to', but the code enforces strictly-less-than: a step equal to the whole span leaves at most one usable value and is rejected.) Hit by sequence DDL whose INCREMENT BY magnitude is >= the declared range.

Source

Thrown at crates/datastore/src/locking_tx_datastore/sequence.rs:42

    }
}

impl Sequence {
    pub(super) fn new(schema: SequenceSchema, previous_allocation: Option<i128>) -> Self {
        if schema.start < schema.min_value || schema.start > schema.max_value {
            panic!(
                "Invalid sequence: start value {} is out of bounds for sequence with min_value {} and max_value {}",
                schema.start, schema.min_value, schema.max_value
            );
        }
        if schema.max_value <= schema.min_value {
            panic!("Invalid sequence: max_value must be greater than min_value");
        }
        if schema.increment == 0 {
            panic!("Invalid sequence: increment must be non-zero");
        }
        if schema.increment.unsigned_abs() >= (schema.max_value - schema.min_value) as u128 {
            panic!(
                "Invalid sequence: increment must be less than or equal to the range between min_value and max_value"
            );
        }
        let start = if let Some(prev) = previous_allocation {
            if prev < schema.min_value || prev > schema.max_value {
                // Previous versions set allocated to 0 as a default,
                // so we have this special case.
                if prev == 0 {
                    schema.start
                } else {
                    panic!(
                        "Invalid sequence: previous allocation value {prev} is out of bounds for sequence with min_value {} and max_value {}",
                        schema.min_value, schema.max_value
                    );
                }
            } else {
                prev
            }

View on GitHub (pinned to 6dee26c6ef)

Solutions

Reduce |INCREMENT| below (MAXVALUE - MINVALUE), e.g. 1.
Or widen the range so the span exceeds the step magnitude.
Validate increment against the span in migration tooling before applying DDL.

Example fix

-- before: step as large as the whole range
CREATE SEQUENCE s MINVALUE 0 MAXVALUE 10 INCREMENT BY 10;

-- after: step smaller than the range
CREATE SEQUENCE s MINVALUE 0 MAXVALUE 10 INCREMENT BY 1;

Defensive patterns

Strategy: validation

Validate before calling

fn increment_fits_range(s: &SequenceSchema) -> Result<(), String> {
    let span = (s.max_value - s.min_value) as u128;
    if s.increment.unsigned_abs() >= span {
        return Err(format!("|increment| {} must be < range span {}", s.increment.unsigned_abs(), span));
    }
    Ok(())
}

Type guard

fn valid_sequence_schema(s: &SequenceSchema) -> bool {
    s.min_value <= s.start && s.start <= s.max_value
        && s.max_value > s.min_value
        && s.increment != 0
        && s.increment.unsigned_abs() < (s.max_value - s.min_value) as u128
}

Prevention

Cross-check INCREMENT against (MAXVALUE - MINVALUE) in DDL review; the check is strict (<), despite the panic message wording.
Avoid large steps on small test ranges.
Re-validate increments whenever bounds are tightened in migrations.

When it happens

Trigger: Creating a sequence like MINVALUE 0 MAXVALUE 10 INCREMENT BY 10 (or -10), where |increment| >= max_value - min_value.

Common situations: Small test sequences with large steps; negative increments sized to the full range; adjusting MAXVALUE downward without re-checking the increment.

Related errors

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