golang-migrate/migrate · error

no config

Error message

no config

What it means

ErrNilConfig is the sentinel error returned by the pgx v5 driver when a nil *Config is passed to WithInstance or WithConnection. The library requires a Config struct (at minimum nothing, but the pointer itself must be non-nil) to initialize defaults like the migrations table name. It exists so callers can use errors.Is to detect the misconfiguration.

Source

Thrown at database/pgx/v5/pgx.go:39

	"github.com/jackc/pgerrcode"
	"github.com/jackc/pgx/v5/pgconn"
	_ "github.com/jackc/pgx/v5/stdlib"
)

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

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

	DefaultMigrationsTable       = "schema_migrations"
	DefaultMultiStatementMaxSize = 10 * 1 << 20 // 10 MB
)

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

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

type Postgres struct {
	// Locking and unlocking need to use the same connection

View on GitHub (pinned to 01a9643f14)

Solutions

1. Pass a non-nil *pgxv5.Config, even an empty one: &pgxv5.Config{}.
2. Check whether WithInstance/WithConnection accepts nil and instead rely on Open(url) if you have no settings to provide.
3. Audit your config-construction path for functions that can return (nil, nil) and fix the error handling.
4. Use errors.Is(err, pgxv5.ErrNilConfig) in your call site to detect and log this specific misconfiguration.

Example fix

// before
var cfg *pgxv5.Config
drv, err := pgxv5.WithInstance(conn, cfg) // ErrNilConfig
// after
cfg := &pgxv5.Config{MigrationsTable: "schema_migrations"}
drv, err := pgxv5.WithInstance(conn, cfg)

if cfg == nil {
    cfg = &pgxv5.Config{MigrationsTable: "schema_migrations"}
}

func hasConfig(c *pgxv5.Config) bool { return c != nil }

drv, err := pgxv5.WithInstance(conn, cfg)
if err != nil {
    if errors.Is(err, pgxv5.ErrNilConfig) {
        return fmt.Errorf("programming error: Config must not be nil: %w", err)
    }
    return err
}

When it happens

Trigger: Calling pgxv5.WithInstance(conn, nil) or pgxv5.WithConnection(conn, nil) — i.e. passing a nil *pgxv5.Config pointer — commonly when a config-building function returns a nil pointer on an error path that the caller ignored.

Common situations: Refactoring code that previously took no config; a helper that conditionally returns nil Config; using a struct value that was declared as a pointer and never initialized; copying examples that omit Config creation.

Related errors

• no config
• no config
• no config
• no config
• unable to parse option x-migrations-table-quoted: %w

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