golang-migrate/migrate · error

database driver: unknown driver %v (forgotten import?)

Error message

database driver: unknown driver %v (forgotten import?)

What it means

database.Open looks up the registered driver by URL scheme in a global registry populated via database.Register, which drivers trigger in their package init(). If no driver is registered for the URL's scheme, this "unknown driver %v (forgotten import?)" error is returned. The message hints at the usual cause: the driver package was never imported, so its init never ran.

Source

Thrown at database/driver.go:95

	// Drop deletes everything in the database.
	// Note that this is a breaking action, a new call to Open() is necessary to
	// ensure subsequent calls work as expected.
	Drop() error
}

// Open returns a new driver instance.
func Open(url string) (Driver, error) {
	scheme, err := iurl.SchemeFromURL(url)
	if err != nil {
		return nil, err
	}

	driversMu.RLock()
	d, ok := drivers[scheme]
	driversMu.RUnlock()
	if !ok {
		return nil, fmt.Errorf("database driver: unknown driver %v (forgotten import?)", scheme)
	}

	return d.Open(url)
}

// Register globally registers a driver.
func Register(name string, driver Driver) {
	driversMu.Lock()
	defer driversMu.Unlock()
	if driver == nil {
		panic("Register driver is nil")
	}
	if _, dup := drivers[name]; dup {
		panic("Register called twice for driver " + name)
	}
	drivers[name] = driver
}

View on GitHub (pinned to 01a9643f14)

Solutions

1. Add a blank import of the driver package: _ "github.com/golang-migrate/migrate/v4/database/<driver>".
2. Verify the URL scheme matches a registered driver name (check the driver package's init/Register call, e.g. "postgres", "mysql", "cassandra").
3. Check build tags/constraints aren't excluding the driver file from compilation, and that no import-cleanup removed the blank import.

Example fix

// before
import (
    "github.com/golang-migrate/migrate/v4"
)
// after
import (
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/file"
    "github.com/golang-migrate/migrate/v4"
)

import (
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

m, err := migrate.Open(dsn)
if err != nil {
    if strings.Contains(err.Error(), "unknown driver") {
        return fmt.Errorf("scheme %q has no registered driver; add the blank import for the driver package", schemeOf(dsn))
    }
    return err
}

When it happens

Trigger: Calling migrate.Open/database.Open with a scheme (postgres, mysql, cassandra, etc.) whose driver package (e.g. _ "github.com/golang-migrate/migrate/v4/database/postgres") is not imported; misspelled or unsupported scheme in the URL.

Common situations: Blank imports removed by an IDE auto-cleanup; using a scheme name that doesn't match the registered one (e.g. "postgresql://" when only "postgres" is registered without a glue driver); switching drivers between dev and prod without updating imports; building with build tags excluding the driver.

Related errors

• no config
• no keyspace provided
• no config
• no database name
• no schema

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