{"record":{"id":"4012cda7c9c00cd6","repo":"clockworklabs/SpacetimeDB","slug":"invalid-sequence-start-value-is-out-of-bounds","errorCode":null,"errorMessage":"Invalid sequence: start value {} is out of bounds for sequence with min_value {} and max_value {}","messagePattern":"Invalid sequence: start value (.+?) is out of bounds for sequence with min_value (.+?) and max_value (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/datastore/src/locking_tx_datastore/sequence.rs","lineNumber":30,"sourceCode":"    value: i128,\n    // The number we have persisted as a lower bound for the next restart.\n    // This is the first value to be returned after a restart, so when we\n    // reach this value, the user needs to call allocate_steps and update\n    // the corresponding system table row.\n    allocated: i128,\n}\n\nimpl MemoryUsage for Sequence {\n    fn heap_usage(&self) -> usize {\n        // MEMUSE: intentionally ignoring schema\n        self.value.heap_usage()\n    }\n}\n\nimpl Sequence {\n    pub(super) fn new(schema: SequenceSchema, previous_allocation: Option<i128>) -> Self {\n        if schema.start < schema.min_value || schema.start > schema.max_value {\n            panic!(\n                \"Invalid sequence: start value {} is out of bounds for sequence with min_value {} and max_value {}\",\n                schema.start, schema.min_value, schema.max_value\n            );\n        }\n        if schema.max_value <= schema.min_value {\n            panic!(\"Invalid sequence: max_value must be greater than min_value\");\n        }\n        if schema.increment == 0 {\n            panic!(\"Invalid sequence: increment must be non-zero\");\n        }\n        if schema.increment.unsigned_abs() >= (schema.max_value - schema.min_value) as u128 {\n            panic!(\n                \"Invalid sequence: increment must be less than or equal to the range between min_value and max_value\"\n            );\n        }\n        let start = if let Some(prev) = previous_allocation {\n            if prev < schema.min_value || prev > schema.max_value {\n                // Previous versions set allocated to 0 as a default,","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/6dee26c6efc2856793e12b148a59742964f5d783/crates/datastore/src/locking_tx_datastore/sequence.rs#L12-L48","documentation":"Sequence::new validates a SequenceSchema before creating a sequence; the first invariant requires min_value <= start <= max_value. A start outside the declared bounds panics with all three values printed. Reached when DDL (or programmatic schema) defines a sequence, including auto-increment columns, with a start outside its range. Note Sequence::new also takes a previous_allocation (used when reloading schema) and tolerates the legacy default of 0 from older versions, so this specific panic is about the schema's declared start, not prior allocations.","triggerScenarios":"Creating or altering a sequence where START WITH is below MINVALUE or above MAXVALUE, e.g. START WITH 100 MINVALUE 0 MAXVALUE 50; also migrations that shrink bounds below an existing declared start.","commonSituations":"Hand-written sequence DDL with inconsistent bounds; copy-pasted sequence options between columns; migrations lowering MAXVALUE after data exists.","solutions":["Set START WITH inside [MINVALUE, MAXVALUE], or omit START to default to MINVALUE.","Widen MINVALUE/MAXVALUE to cover the intended start value.","When migrating existing sequences, recompute bounds from the current allocated value before applying."],"exampleFix":"-- before: start outside bounds (100 > MAXVALUE 50)\nCREATE SEQUENCE order_seq START WITH 100 MINVALUE 0 MAXVALUE 50;\n\n-- after: start within bounds\nCREATE SEQUENCE order_seq START WITH 10 MINVALUE 0 MAXVALUE 1000 INCREMENT BY 1;","handlingStrategy":"validation","validationCode":"fn validate_sequence(s: &SequenceSchema) -> Result<(), String> {\n    if s.start < s.min_value || s.start > s.max_value {\n        return Err(format!(\"start {} outside [{}, {}]\", s.start, s.min_value, s.max_value));\n    }\n    if s.max_value <= s.min_value { return Err(\"max_value must be > min_value\".into()); }\n    if s.increment == 0 { return Err(\"increment must be non-zero\".into()); }\n    if s.increment.unsigned_abs() >= (s.max_value - s.min_value) as u128 {\n        return Err(\"|increment| must be < (max_value - min_value)\".into());\n    }\n    Ok(())\n}","typeGuard":"fn valid_sequence_schema(s: &SequenceSchema) -> bool {\n    s.min_value <= s.start && s.start <= s.max_value\n        && s.max_value > s.min_value\n        && s.increment != 0\n        && s.increment.unsigned_abs() < (s.max_value - s.min_value) as u128\n}","tryCatchPattern":null,"preventionTips":["Validate sequence options in migration tooling before applying DDL.","Prefer defaults (omit START/INCREMENT) unless explicit bounds are required.","When shrinking a sequence range, recompute bounds against the current allocated value first."],"tags":["sql","sequence","ddl","schema-validation","spacetimedb"],"backgroundTag":"sequence-definition-invalid","analyzedSha":"6dee26c6efc2856793e12b148a59742964f5d783","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}