golang-migrate/migrate · error

no config

Error message

no config

What it means

ErrNilConfig is the pgx (Postgres) driver's sentinel meaning WithInstance or WithConnection was given a nil *Config. The driver guarantees its internal config is never nil and therefore rejects a nil argument up front instead of dereferencing it. Declared at database/pgx/pgx.go:48; raised in WithInstance (line 79-81) and WithConnection.

Source

Thrown at database/pgx/pgx.go:48

)

func init() {
	db := Postgres{}
	database.Register("pgx", &db)
	database.Register("pgx4", &db)
}

var (
	multiStmtDelimiter = []byte(";")

	DefaultMigrationsTable       = "schema_migrations"
	DefaultMultiStatementMaxSize = 10 * 1 << 20 // 10 MB
	DefaultLockTable             = "schema_lock"
	DefaultLockStrategy          = LockStrategyAdvisory
)

var (
	ErrNilConfig      = fmt.Errorf("no config")
	ErrNoDatabaseName = fmt.Errorf("no database name")
	ErrNoSchema       = fmt.Errorf("no schema")
	ErrDatabaseDirty  = fmt.Errorf("database is dirty")
)

type Config struct {
	MigrationsTable       string
	DatabaseName          string
	SchemaName            string
	LockTable             string
	LockStrategy          string
	migrationsSchemaName  string
	migrationsTableName   string
	StatementTimeout      time.Duration
	MigrationsTableQuoted bool
	MultiStatementEnabled bool
	MultiStatementMaxSize int
}

View on GitHub (pinned to 01a9643f14)

Solutions

1. Pass a valid &pgx.Config{} with at least DatabaseName or rely on WithInstance to auto-detect it
2. Handle the error from your config-construction function so nil never reaches WithInstance
3. Add an explicit nil check for the *Config at your application boundary

Example fix

// before
var cfg *pgx.Config
drv, err := pgx.WithInstance(db, cfg) // nil
// after
cfg := &pgx.Config{ DatabaseName: "app" }
drv, err := pgx.WithInstance(db, cfg)

func validatePgxConfig(cfg *pgx.Config) error {
    if cfg == nil {
        return errors.New("pgx config must not be nil; use &pgx.Config{} for defaults")
    }
    return nil
}

func hasPgxConfig(cfg *pgx.Config) bool { return cfg != nil }

drv, err := pgx.WithInstance(db, cfg)
if errors.Is(err, pgx.ErrNilConfig) {
    return fmt.Errorf("pgx: nil config passed; construct &pgx.Config{}: %w", err)
}

When it happens

Trigger: Calling pgx.WithInstance(db, nil) or pgx.WithConnection(conn, nil); passing a *Config that is nil because an earlier constructor/parse step failed and its error was ignored.

Common situations: Building migrations in a wiring layer where Config is produced conditionally; upgrading code that previously used a non-pointer Config; test scaffolding that forgets to construct a Config.

Related errors

• no config
• no schema
• "%s" MigrationsTable contains too many dot characters
• no database name
• database is dirty

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