golang-migrate/migrate · critical

Register driver is nil

Error message

Register driver is nil

What it means

source.Register panics when the migration-source driver argument is nil. Source drivers (file, iofs, pkger, etc.) are stored in a global map by name; a nil entry would panic on later lookup/use, so registration rejects it eagerly.

Source

Thrown at source/driver.go:101

		return nil, fmt.Errorf("source driver: invalid URL scheme")
	}

	driversMu.RLock()
	d, ok := drivers[u.Scheme]
	driversMu.RUnlock()
	if !ok {
		return nil, fmt.Errorf("source driver: unknown driver '%s' (forgotten import?)", u.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
}

// List lists the registered drivers
func List() []string {
	driversMu.RLock()
	defer driversMu.RUnlock()
	names := make([]string, 0, len(drivers))
	for n := range drivers {
		names = append(names, n)
	}
	return names
}

View on GitHub (pinned to 01a9643f14)

Solutions

1. Construct the source Driver before registering and propagate any constructor errors.
2. Avoid nil typed-interface values; compare against nil carefully before Register.
3. Move registration out of init() into explicit setup code if initialization can fail.

Example fix

// before
func init() { source.Register("mem", s) } // s nil when setup failed
// after
func init() {
	if s == nil { panic("source driver not initialized") }
	source.Register("mem", s)
}

if srcDrv == nil {
	panic("refusing to call source.Register with nil driver")
}
source.Register(name, srcDrv)

func isNilSource(s source.Driver) bool {
	if s == nil { return true }
	return reflect.ValueOf(s).Kind() == reflect.Ptr && reflect.ValueOf(s).IsNil()
}

defer func() {
	if r := recover(); r != nil {
		if s, ok := r.(string); ok && s == "Register driver is nil" {
			log.Fatalf("nil source driver: check driver initialization order")
		}
		panic(r)
	}
}()
source.Register(name, srcDrv)

When it happens

Trigger: Calling source.Register("mysrc", nil) or registering an interface variable that is nil because the source driver failed to initialize, typically in a package's init().

Common situations: Custom source drivers registered from init() with a failed constructor, copied boilerplate where the driver was never assigned, or typed-nil interface values passed by mistake.

Related errors

• Register driver is nil
• Register called twice for driver
• Register called twice for driver
• not implemented
• failed to init driver with relative path %q: %w

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