golang-migrate/migrate · error

too many arguments

Error message

too many arguments

What it means

numDownMigrationsFromArgs returns 'too many arguments' when `migrate down` receives more than one positional argument. The down command accepts at most a single limit N (or -all); anything else is ambiguous, so the CLI rejects it.

Source

Thrown at internal/cli/commands.go:246

	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 at most one positional argument: `migrate down N` or `migrate down -all`.
2. Quote variables in shell scripts and avoid forwarding $@ to the CLI.
3. Remove extra tokens such as migration filenames — down takes a count, not a target.
4. In wrapper scripts, validate the arg count before exec'ing migrate.

Example fix

// before
migrate -path ./migrations -database $DB down $ARGS
// after
set -- $ARGS; if [ $# -gt 1 ]; then echo "too many args"; exit 1; fi
migrate -path ./migrations -database $DB down "$@"

if [ $# -gt 1 ]; then
	echo "migrate down accepts at most one argument"; exit 1
fi

When it happens

Trigger: Running `migrate down 1 2`, passing extra free-form arguments, or shell expansion inserting multiple words (unquoted variables, globs) after the subcommand.

Common situations: Users passing migration names/targets to down expecting v1-style behavior; unquoted $@ or glob expansion in scripts adding extra words; copy-pasted commands with stray tokens.

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
• can't read limit argument N
• 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/5d9968c8f08da772. Report an issue: GitHub.