golang-migrate/migrate · error

no config

Error message

no config

What it means

ErrNilConfig in database/mysql is returned by WithInstance, WithConnection and extractCustomQueryParams when the *Config argument is nil. The MySQL driver needs Config for DatabaseName and MigrationsTable, so a nil config makes migration state tracking impossible. It is a caller-side configuration bug.

Source

Thrown at database/mysql/mysql.go:34

	"strings"
	"sync/atomic"
	"time"

	"github.com/go-sql-driver/mysql"
	"github.com/golang-migrate/migrate/v4/database"
)

var _ database.Driver = (*Mysql)(nil) // explicit compile time type check

func init() {
	database.Register("mysql", &Mysql{})
}

var DefaultMigrationsTable = "schema_migrations"

var (
	ErrDatabaseDirty    = fmt.Errorf("database is dirty")
	ErrNilConfig        = fmt.Errorf("no config")
	ErrNoDatabaseName   = fmt.Errorf("no database name")
	ErrAppendPEM        = fmt.Errorf("failed to append PEM")
	ErrTLSCertKeyConfig = fmt.Errorf("to use TLS client authentication, both x-tls-cert and x-tls-key must not be empty")
)

type Config struct {
	MigrationsTable  string
	DatabaseName     string
	NoLock           bool
	StatementTimeout time.Duration
}

type Mysql struct {
	// mysql RELEASE_LOCK must be called from the same conn, so
	// just do everything over a single conn anyway.
	conn     *sql.Conn
	db       *sql.DB
	isLocked atomic.Bool

View on GitHub (pinned to 01a9643f14)

Solutions

1. Pass a non-nil *mysql.Config to WithInstance/WithConnection
2. Use mysql.WithConfig/WithInstance with a proper DSN so config is built for you
3. Add a nil-check in your driver bootstrap before constructing migrate

Example fix

// before
var cfg *mysql.Config
d, err := mysql.WithInstance(sqlDB, cfg)
// after
cfg := &mysql.Config{DatabaseName: "app", MigrationsTable: "schema_migrations"}
d, err := mysql.WithInstance(sqlDB, cfg)

if cfg == nil {
    return fmt.Errorf("mysql migration requires non-nil *mysql.Config")
}

func hasMysqlConfig(cfg *mysql.Config) bool { return cfg != nil }

if err != nil {
    if errors.Is(err, mysql.ErrNilConfig) {
        return fmt.Errorf("nil mysql config passed to driver construction")
    }
    return err
}

When it happens

Trigger: mysql.WithInstance(db, nil); mysql.WithConnection(ctx, db, nil); a nil config flowing into extractCustomQueryParams through Open.

Common situations: Declaring `var cfg *mysql.Config` without assigning, wrappers that pass through nil, refactors replacing WithConfig with manual struct construction.

Related errors

• no config
• no config
• no database name
• no config
• no config

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