gastownhall/beads · error
legacy SQLite %s is %d (current INT range %d..%d)
Error message
legacy SQLite %s is %d (current INT range %d..%d)
What it means
A legacy SQLite integer column (sql.NullInt64) holds a value outside the current schema's 32-bit INT range (-2147483648..2147483647). The reader validates integer fields during validate() so values that would overflow the current Dolt INT columns are rejected before any write, instead of silently wrapping or failing deep in the driver.
Source
Thrown at internal/migration/legacysqlite/reader.go:758
func checkCurrentVarchars(fields ...currentVarchar) error {
for _, field := range fields {
if n := utf8.RuneCountInString(field.value); n > field.maxRunes {
return fmt.Errorf("legacy SQLite %s is %d characters (current VARCHAR(%d) maximum)", field.name, n, field.maxRunes)
}
}
return nil
}
type currentInt struct {
name string
value sql.NullInt64
}
func checkCurrentInts(fields ...currentInt) error {
for _, field := range fields {
if field.value.Valid && (field.value.Int64 < math.MinInt32 || field.value.Int64 > math.MaxInt32) {
return fmt.Errorf("legacy SQLite %s is %d (current INT range %d..%d)", field.name, field.value.Int64, math.MinInt32, math.MaxInt32)
}
}
return nil
}
func nonempty(values ...sql.NullString) bool {
for _, v := range values {
if v.Valid && v.String != "" {
return true
}
}
return false
}
func nullString(v sql.NullString) string {
if v.Valid {
return v.String
}
return ""View on GitHub (pinned to 71377f2769)
Solutions
- Find the column named in the error and UPDATE it in the legacy SQLite DB to a value within -2147483648..2147483647 before migrating.
- If the value is a sentinel/garbage (e.g. 9999999999), reset it to the schema default (often NULL or 2 for priority).
- Audit the legacy DB with a query like SELECT * FROM issues WHERE <col> NOT BETWEEN -2147483648 AND 2147483647 to catch all offending rows at once.
- Check for tools or scripts outside bd that wrote to the SQLite file and fix them to use int32-safe values.
Example fix
// before: priority stored as 4294967295 UPDATE issues SET priority = 2 WHERE priority > 2147483647; // after: value fits current INT range
Defensive patterns
Strategy: validation
Validate before calling
func intFitsCurrentSchema(v int64) bool {
return v >= -2147483648 && v <= 2147483647
}
// SELECT ... WHERE col < -2147483648 OR col > 2147483647 on all int columns first Type guard
func isInt32Safe(v int64) bool {
return v >= math.MinInt32 && v <= math.MaxInt32
} Prevention
- Query all integer columns for values outside [-2147483648, 2147483647] before migration and clamp them.
- Avoid writing sentinel or overflowed integers via external tools into the SQLite DB.
- Upgrade old bd versions through supported paths so integer columns are normalized.
When it happens
Trigger: Running the legacy-SQLite migration when a numeric column (e.g. priority, counter columns checked by checkCurrentInts) stores a value beyond int32 range, such as an extreme value written by an old or buggy bd build, or a manually edited database.
Common situations: Databases corrupted by integer overflow bugs in older versions; manual SQL edits inserting sentinel values like 9999999999; external tools writing SQLite rows directly; clock or epoch values stored in milliseconds that exceed int32.
Related errors
- legacy SQLite foreign-key drift in %s
- legacy SQLite %s is %d characters (current VARCHAR(%d) maxim
- sealed legacy SQLite database does not match source fingerpr
- sealed legacy SQLite WAL does not match source fingerprint
- legacy SQLite source changed while sealing
AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30).
Data as JSON: /api/errors/060b8ef9c05ad21b.
Report an issue: GitHub.