golang-migrate/migrate · error

next sequence number %s too large, at most %d digits are all

Error message

next sequence number %s too large, at most %d digits are allowed

What it means

When creating a seq migration with a fixed digit width (`-seqdigits N`), the computed next sequence number, zero-padded to N digits, exceeds that width (e.g. 100000 with 5 digits). The CLI rejects the creation instead of emitting a version wider than configured, which would break lexicographic ordering assumptions.

Source

Thrown at internal/cli/commands.go:53

		if idx < 1 { // Using 1 instead of 0 since there should be at least 1 digit
			return "", fmt.Errorf("malformed migration filename: %s", filename)
		}

		var err error
		matchSeqStr = matchSeqStr[0:idx]
		nextSeq, err = strconv.ParseUint(matchSeqStr, 10, 64)

		if err != nil {
			return "", err
		}

		nextSeq++
	}

	version := fmt.Sprintf("%0[2]*[1]d", nextSeq, seqDigits)

	if len(version) > seqDigits {
		return "", fmt.Errorf("next sequence number %s too large, at most %d digits are allowed", version, seqDigits)
	}

	return version, nil
}

func timeVersion(startTime time.Time, format string) (version string, err error) {
	switch format {
	case "":
		err = errInvalidTimeFormat
	case "unix":
		version = strconv.FormatInt(startTime.Unix(), 10)
	case "unixNano":
		version = strconv.FormatInt(startTime.UnixNano(), 10)
	default:
		version = startTime.Format(format)
	}

	return

View on GitHub (pinned to 01a9643f14)

Solutions

1. Increase the digit width, e.g. `migrate create -seq -seqdigits 6 ...`, so the next number fits (existing shorter files still sort correctly due to zero-padding).
2. Remove or renumber old migrations if they are no longer needed (only if safe — migrations may already be applied).
3. Check the highest sequence number in the directory and confirm it against the configured width before creating more migrations.
4. Switch to timestamp versions (`-format`) for new migrations if sequence exhaustion keeps recurring, accepting the mixed-format implications.

Example fix

// before
migrate create -seq -seqdigits 5 -ext sql -name add_index
// after (00000 max reached)
migrate create -seq -seqdigits 6 -ext sql -name add_index

maxSeq := 0
for _, f := range migrationFiles {
    n, _ := strconv.Atoi(strings.SplitN(filepath.Base(f), "_", 2)[0])
    if n > maxSeq { maxSeq = n }
}
if maxSeq+1 >= int(math.Pow10(seqDigits)) {
    return fmt.Errorf("next seq %d will not fit in %d digits; increase -seqdigits", maxSeq+1, seqDigits)
}

err := createCmd(dir, time.Now(), "", name, ext, true, seqDigits, true)
if err != nil && strings.Contains(err.Error(), "too large") {
    // rerun with a larger -seqdigits value
}

When it happens

Trigger: `migrate create -seq -seqdigits N ...` when the largest existing migration's sequence is >= 10^N - 1, so the incremented number no longer fits in N digits.

Common situations: Long-lived project that outgrew the default/forced digit width; someone lowered -seqdigits below the existing max sequence; a huge hand-written sequence number in an existing file pushes nextSeq over the cap.

Related errors

• duplicate migration version: %s
• malformed migration filename: %s
• unable to parse file %v
• digits must be positive
• the seq and format options are mutually exclusive

AI-assisted analysis of golang-migrate/migrate@01a9643f14 (2026-09-02). Data as JSON: /api/errors/69bc2c4aa7fa9f6f. Report an issue: GitHub.