What causes "expected instance of pkging.Pkger" in golang-migrate/migrate?

Pass a real pkger instance, e.g. pkger.WithInstance(pkger.New(), "/migrations").

expected instance of pkging.Pkger

Error message

expected instance of pkging.Pkger

What it means

source/pkger.WithInstance requires a non-nil pkging.Pkger instance because the driver is backed entirely by that embedded filesystem. Passing nil would panic later when wrapping instance.Open into an http.FileSystem, so the function returns "expected instance of pkging.Pkger" immediately.

Source

Thrown at source/pkger/pkger.go:57

			return nil, err
		}
		return f.(http.File), nil
	})

	if err := p.Init(fs, u.Path); err != nil {
		return nil, fmt.Errorf("failed to init driver with relative path %q: %w", u.Path, err)
	}

	return p, nil
}

// WithInstance returns a source.Driver that is backed by an instance of
// pkging.Pkger. The relative location of migrations is indicated by path. The
// path must exist on the pkging.Pkger instance for the driver to initialize
// successfully.
func WithInstance(instance pkging.Pkger, path string) (source.Driver, error) {
	if instance == nil {
		return nil, fmt.Errorf("expected instance of pkging.Pkger")
	}

	// wrap pkger to implement http.FileSystem.
	fs := fsFunc(func(name string) (http.File, error) {
		f, err := instance.Open(name)
		if err != nil {
			return nil, err
		}
		return f.(http.File), nil
	})

	var p Pkger

	if err := p.Init(fs, path); err != nil {
		return nil, fmt.Errorf("failed to init driver with relative path %q: %w", path, err)
	}

	return &p, nil

View on GitHub (pinned to 01a9643f14)

Solutions

Pass a real pkger instance, e.g. pkger.WithInstance(pkger.New(), "/migrations").
Check the variable feeding WithInstance for nil before calling it, including typed-nil interface cases.
If you don't need a custom instance, use source/pkger's Open(url) instead of WithInstance.

Example fix

// before
var p pkging.Pkger
src, err := pkger.WithInstance(p, "/migrations") // panics/errs: nil
// after
p := pkger.New()
src, err := pkger.WithInstance(p, "/migrations")

Defensive patterns

Strategy: validation

Validate before calling

var p pkging.Pkger = buildPkger()
if p == nil {
	return errors.New("pkger instance must be non-nil before WithInstance")
}
src, err := pkger.WithInstance(p, "/migrations")

Type guard

func isNilInterface(v interface{}) bool {
	if v == nil { return true }
	rv := reflect.ValueOf(v)
	switch rv.Kind() {
	case reflect.Ptr, reflect.Interface, reflect.Map, reflect.Slice:
		return rv.IsNil()
	}
	return false
}

Try / catch

if err != nil {
	if err.Error() == "expected instance of pkging.Pkger" {
		return fmt.Errorf("pkger instance not initialized: %w", err)
	}
	return err
}

Prevention

Construct the pkger instance immediately before WithInstance, not in a separate failure-prone step.
Never assign to an interface variable from a function that can return nil on error.
Document that WithInstance requires a live pkging.Pkger, not a typed nil.

When it happens

Trigger: Calling pkger.WithInstance(nil, "/migrations"), typically because a variable holding the pkger instance was never initialized or an interface value is a nil *pkgs.Pkgs typed nil.

Common situations: Refactoring code so the pkger instance is conditionally created, dependency-injection wiring that leaves the instance nil, or passing a typed nil interface from another package.

Related errors

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