golang-migrate/migrate · error

no config

Error message

no config

What it means

ErrNilConfig is a sentinel error returned by the ql driver's WithInstance and WithConnection when the *Config argument is nil. The driver requires a non-nil config (even if only a MigrationsTable default is applied from it) to initialize. Cassandra and redshift redeclare the same sentinel for their own WithInstance functions.

Source

Thrown at database/ql/ql.go:24

	"fmt"
	"io"
	nurl "net/url"
	"strings"
	"sync/atomic"

	"github.com/golang-migrate/migrate/v4"
	"github.com/golang-migrate/migrate/v4/database"
	_ "modernc.org/ql/driver"
)

func init() {
	database.Register("ql", &Ql{})
}

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")
)

type Config struct {
	MigrationsTable string
	DatabaseName    string
}

type Ql struct {
	db       *sql.DB
	isLocked atomic.Bool

	config *Config
}

func WithInstance(instance *sql.DB, config *Config) (database.Driver, error) {
	if config == nil {

View on GitHub (pinned to 01a9643f14)

Solutions

1. Pass a non-nil &ql.Config{} — at minimum &ql.Config{MigrationsTable: ql.DefaultMigrationsTable}
2. Include the required DatabaseName value in the config if using WithInstance
3. Prefer the Open(dsn) path so the driver builds the config from the URL

Example fix

// before
driver, err := ql.WithInstance(instance, nil)
// after
driver, err := ql.WithInstance(instance, &ql.Config{DatabaseName: "mydb", MigrationsTable: ql.DefaultMigrationsTable})

func validateQLConfig(cfg *ql.Config) error {
    if cfg == nil {
        return errors.New("ql config must not be nil")
    }
    if cfg.MigrationsTable == "" {
        cfg.MigrationsTable = ql.DefaultMigrationsTable
    }
    return nil
}

func hasConfig(cfg *ql.Config) bool { return cfg != nil }

When it happens

Trigger: Calling database.WithInstance(instance, nil) or ql.WithConnection(conn, nil) without constructing a Config struct.

Common situations: Programmatic use of the driver without the URL-based Open path, e.g. embedding migrate in an application and forgetting to build the Config; refactors that drop the config argument.

Related errors

• no database name
• no config
• URL cannot be empty
• "%s" MigrationsTable contains too many dot characters
• x-migrations-table must be quoted (for instance '"migrate"."

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