golang-migrate/migrate · error
no config
Error message
no config
What it means
ErrNilConfig is the sentinel error database/postgres (and copies in cassandra, pgx, cockroachdb, etc.) returns from WithInstance/WithConnection/Open when the *Config argument is nil. It signals a programming mistake: the driver was invoked without required configuration. Compare with errors.Is(err, postgres.ErrNilConfig).
Source
Thrown at database/postgres/postgres.go:38
"github.com/golang-migrate/migrate/v4/database/multistmt"
"github.com/lib/pq"
)
func init() {
db := Postgres{}
database.Register("postgres", &db)
database.Register("postgresql", &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")
ErrDatabaseDirty = fmt.Errorf("database is dirty")
)
type Config struct {
MigrationsTable string
MigrationsTableQuoted bool
MultiStatementEnabled bool
DatabaseName string
SchemaName string
migrationsSchemaName string
migrationsTableName string
StatementTimeout time.Duration
MultiStatementMaxSize int
}
type Postgres struct {View on GitHub (pinned to 01a9643f14)
Solutions
- Always pass a non-nil *postgres.Config (at minimum set DatabaseName or let Open derive it from the URL)
- Check errors.Is(err, postgres.ErrNilConfig) to branch on this specific case
- If config comes from another function, nil-check it before calling WithInstance/WithConnection
Example fix
// before
driver, err := postgres.WithInstance(conn, nil)
// after
cfg := &postgres.Config{DatabaseName: "mydb"}
driver, err := postgres.WithInstance(conn, cfg) Defensive patterns
Strategy: validation
Validate before calling
if cfg == nil {
return nil, errors.New("postgres config is required")
}
driver, err := postgres.WithInstance(conn, cfg) Type guard
func configProvided(cfg *postgres.Config) bool { return cfg != nil } Try / catch
if err != nil {
if errors.Is(err, postgres.ErrNilConfig) {
log.Fatal("a *postgres.Config must be passed to WithInstance/WithConnection")
}
panic(err)
} Prevention
- Never pass nil for *Config; build at least an empty &postgres.Config{} with required fields
- Nil-check configuration structs constructed from env vars before use
- Use errors.Is against exported sentinels (ErrNilConfig, ErrNoDatabaseName) for precise handling
When it happens
Trigger: Calling postgres.WithInstance(conn, nil) or postgres.WithConnection(conn, nil); passing a nil *Config from a wrapper; the cassandra/pgx variants likewise return their local ErrNilConfig when config == nil.
Common situations: Constructing the driver manually instead of via URL-driven Open and forgetting to build a Config struct; reflection-based or DI wiring that yields a nil pointer; refactors that made Config optional in a caller's eyes.
Related errors
AI-assisted analysis of golang-migrate/migrate@01a9643f14 (2026-09-02).
Data as JSON: /api/errors/eb960c21bd43c165.
Report an issue: GitHub.