golang-migrate/migrate · error

digits must be positive

Error message

digits must be positive

What it means

errInvalidSequenceWidth ('digits must be positive') is returned by nextSeqVersion in internal/cli when the migrate create -seq command is invoked with a -digits value <= 0. Sequential migration version numbers are zero-padded to the given width, so at least one digit is required. It is package-private and returned to TestNextSeqVersion/TestCreateCmd.

Source

Thrown at internal/cli/commands.go:18

package cli

import (
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"strconv"
	"strings"
	"time"

	"github.com/golang-migrate/migrate/v4"
	_ "github.com/golang-migrate/migrate/v4/database/stub" // TODO remove again
	_ "github.com/golang-migrate/migrate/v4/source/file"
)

var (
	errInvalidSequenceWidth     = errors.New("digits must be positive")
	errIncompatibleSeqAndFormat = errors.New("the seq and format options are mutually exclusive")
	errInvalidTimeFormat        = errors.New("time format may not be empty")
)

func nextSeqVersion(matches []string, seqDigits int) (string, error) {
	if seqDigits <= 0 {
		return "", errInvalidSequenceWidth
	}

	nextSeq := uint64(1)

	if len(matches) > 0 {
		filename := matches[len(matches)-1]
		matchSeqStr := filepath.Base(filename)
		idx := strings.Index(matchSeqStr, "_")

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

View on GitHub (pinned to 01a9643f14)

Solutions

1. Pass a positive -digits value, e.g. -digits 4 (the default width).
2. Omit the -digits flag to use the default.
3. Validate the digits value in your wrapper script before invoking the CLI.
4. If digits is sourced from a variable, check it is a positive integer first.

Example fix

// before
migrate create -seq -digits 0 -ext sql -dir migrations add_users
// after
migrate create -seq -digits 4 -ext sql -dir migrations add_users

if [ -n "$DIGITS" ] && [ "$DIGITS" -le 0 ] 2>/dev/null; then
	echo "-digits must be a positive integer"; exit 1
fi

When it happens

Trigger: Running `migrate create -seq -digits 0` or `-digits -1 ...` (any digits value not a positive integer) so nextSeqVersion receives seqDigits <= 0.

Common situations: Scripting the CLI with a computed digits value that ends up 0; typo like -digits 0 when trying to get unpadded output; templated CI pipelines with an unset/empty variable defaulting to 0.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

• can't read limit argument N
• too many arguments
• the seq and format options are mutually exclusive
• time format may not be empty
• -all cannot be used with other arguments

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