golang-migrate/migrate · error

can't read limit argument N

Error message

can't read limit argument N

What it means

When `migrate down N` is given a positional argument that is not a valid unsigned integer, numDownMigrationsFromArgs fails strconv.ParseUint(downValue, 10, 64) and returns 'can't read limit argument N'. The library treats the single argument as the number of migrations to roll back, so it must parse as a base-10 uint64.

Source

Thrown at internal/cli/commands.go:242

// numDownMigrationsFromArgs returns an int for number of migrations to apply
// and a bool indicating if we need a confirm before applying
func numDownMigrationsFromArgs(applyAll bool, args []string) (int, bool, error) {
	if applyAll {
		if len(args) > 0 {
			return 0, false, errors.New("-all cannot be used with other arguments")
		}
		return -1, false, nil
	}

	switch len(args) {
	case 0:
		return -1, true, nil
	case 1:
		downValue := args[0]
		n, err := strconv.ParseUint(downValue, 10, 64)
		if err != nil {
			return 0, false, errors.New("can't read limit argument N")
		}
		return int(n), false, nil
	default:
		return 0, false, errors.New("too many arguments")
	}
}

View on GitHub (pinned to 01a9643f14)

Solutions

1. Pass a non-negative integer, e.g. `migrate down 1`.
2. Validate the value in wrapper scripts (regex ^[0-9]+$) before invoking the CLI.
3. Use -all instead of a numeric argument when you intend to revert everything.
4. Check the variable supplying N — empty strings and floats are common culprits.

Example fix

// before
migrate -path ./migrations -database $DB down "$STEPS"
// after
case "$STEPS" in ''|*[!0-9]*) echo "STEPS must be a positive integer"; exit 1;; esac
migrate -path ./migrations -database $DB down "$STEPS"

case "$N" in ''|*[!0-9]*) echo "N must be a non-negative integer"; exit 1;; esac

func isCount(s string) bool {
	_, err := strconv.ParseUint(s, 10, 64)
	return err == nil
}

When it happens

Trigger: Running `migrate down abc`, `down 3.5`, `down -1`, or `down 99999999999999999999` (overflow) so ParseUint returns an error.

Common situations: Passing a variable that is empty or non-numeric in scripts; a negative count that users expect to mean 'last N'; pasting commands where the argument is a migration filename instead of a count.

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

• digits must be positive
• 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/71a841b63ad0da15. Report an issue: GitHub.