golang-migrate/migrate · error

the seq and format options are mutually exclusive

Error message

the seq and format options are mutually exclusive

What it means

errIncompatibleSeqAndFormat ('the seq and format options are mutually exclusive') is returned by createCmd when -seq is passed together with an explicit -format other than the default time format. Sequential numbering (000001_name.up.sql) and time-based versioning (unix/Nano/time.Time format strings) are two different version schemes and cannot be combined.

Source

Thrown at internal/cli/commands.go:19

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. Remove the -format flag when using -seq.
2. Remove -seq if you want a specific -format (time-based versions).
3. In wrapper scripts, make the flags mutually exclusive and pass only one scheme.
4. Keep the project consistent with existing migrations' naming scheme (migrate rejects mixed version schemes).

Example fix

// before
migrate create -seq -format unix -ext sql -dir migrations add_orders
// after
migrate create -seq -ext sql -dir migrations add_orders

if [ -n "$SEQ" ] && [ -n "$FORMAT" ] && [ "$FORMAT" != "2006-01-02 15:04:05" ]; then
	echo "-seq and -format are mutually exclusive"; exit 1
fi

When it happens

Trigger: Running `migrate create -seq -format unix ...` or `-seq -format 20060102150405 ...` — any explicit -format while -seq is enabled (only the defaultTimeFormat is allowed alongside seq).

Common situations: Copy-pasting CLI invocations that include both flags from different templates; a CI wrapper always injecting -format unix while users add -seq; switching a project from time-based to sequential naming without removing the -format flag.

Related errors

• -all cannot be used with other arguments
• digits must be positive
• time format may not be empty
• can't read limit argument N
• too many arguments

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