golang-migrate/migrate · error

no config

Error message

no config

What it means

The golang-migrate yugabytedb driver returns ErrNilConfig ('no config') when a driver instance is created without a *Config. WithInstance, WithConnection (and WithConfig paths) require a non-nil config holding keyspace, migrations table, and retry settings; without one the driver cannot operate. It is a sentinel error (errors.New) so it can be compared with errors.Is.

Source

Thrown at database/yugabytedb/yugabytedb.go:31

	"github.com/cenkalti/backoff/v4"
	"github.com/golang-migrate/migrate/v4"
	"github.com/golang-migrate/migrate/v4/database"
	"github.com/jackc/pgconn"
	"github.com/jackc/pgerrcode"
	"github.com/lib/pq"
)

const (
	DefaultMaxRetryInterval    = time.Second * 15
	DefaultMaxRetryElapsedTime = time.Second * 30
	DefaultMaxRetries          = 10
	DefaultMigrationsTable     = "migrations"
	DefaultLockTable           = "migrations_locks"
)

var (
	ErrNilConfig          = errors.New("no config")
	ErrNoDatabaseName     = errors.New("no database name")
	ErrMaxRetriesExceeded = errors.New("max retries exceeded")
)

func init() {
	db := YugabyteDB{}
	database.Register("yugabyte", &db)
	database.Register("yugabytedb", &db)
	database.Register("ysql", &db)
}

type Config struct {
	MigrationsTable     string
	LockTable           string
	ForceLock           bool
	DatabaseName        string
	MaxRetryInterval    time.Duration
	MaxRetryElapsedTime time.Duration

View on GitHub (pinned to 01a9643f14)

Solutions

1. Build and pass a &yugabytedb.Config{} (with DatabaseName/KeyspaceName and Defaults, e.g. DefaultMigrationsTable) instead of nil.
2. Check config != nil before calling WithInstance/WithConnection and construct a default config when missing.
3. Compare with errors.Is(err, yugabytedb.ErrNilConfig) to confirm which guard fired and fix the call site.
4. If using Open, ensure the config that gets assembled from the URL is not empty (e.g. include the keyspace in the connection string).

Example fix

// before
m, err := yugabytedb.WithInstance(session, nil)
// after
cfg := &yugabytedb.Config{MigrationsTable: yugabytedb.DefaultMigrationsTable, DatabaseName: "mydb"}
m, err := yugabytedb.WithInstance(session, cfg)

if cfg == nil {
	return nil, errors.New("yugabytedb: config is required")
}
driver, err := yugabytedb.WithInstance(session, cfg)

func validConfig(cfg *yugabytedb.Config) bool { return cfg != nil }

When it happens

Trigger: Calling database/yugabytedb.WithInstance(session, nil) or WithConnection(conn, nil) with a nil *Config; constructing the driver via database.Open with a driver that was handed a nil config.

Common situations: Passing a nil config variable that failed to initialize; refactoring code that used to build a Config; copying driver setup from another database package with a different signature; helper functions that return (config, err) and the nil value is forwarded unchecked.

Related errors

• no database name
• max retries exceeded
• digits must be positive
• the seq and format options are mutually exclusive
• time format may not be empty

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