golang-migrate/migrate · error

open() cannot be called on the httpfs passthrough driver

Error message

open() cannot be called on the httpfs passthrough driver

What it means

The httpfs package provides a passthrough driver built by NewDriver (returning a PartialDriver with Open pre-set). Its Open method is intentionally unimplemented: instances are created via NewDriver, not via the Open(url) factory protocol, so calling Open always returns this error. It exists only to satisfy the source.Driver interface.

Solutions

1. Do not call Open; use the driver instance returned by httpfs.New with source drivers directly, e.g. pass it to source.Open via NewWithSourceDriver.
2. If embedding PartialDriver for a custom driver, implement your own Open(url) that constructs and returns your driver instead of inheriting the panicking passthrough.
3. If you need URL-based construction for http content, use a custom driver whose Open parses the URL and builds an http.FileSystem.

d, err := httpfs.New(http FS) // construct via New; never route it through a URL registry
if err != nil { return err }

drv, err := driver.Open(url)
if err != nil && strings.Contains(err.Error(), "httpfs passthrough") {
    return fmt.Errorf("use httpfs.New() to obtain this driver; Open is not supported")
}

When it happens

Trigger: Calling Open on a driver obtained from httpfs.New (via NewDriver) instead of the already-constructed driver instance; registering the passthrough driver in a scheme registry where Open is then invoked by source.Open(url).

Common situations: Embedding httpfs's driver in a custom source driver and forgetting to override Open; trying to instantiate an http.fs source through the URL-based registry ("httpfs://...") instead of passing the driver directly.

Related errors

• open() cannot be called on the iofs passthrough driver
• source driver: invalid URL scheme
• source driver: unknown driver

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

Appendix: source

Thrown at source/httpfs/driver.go:30

// used as a migration source for the main migrate library.
type driver struct {
	PartialDriver
}

// New creates a new migrate source driver from a http.FileSystem instance and a
// relative path to migration files within the virtual FS.
func New(fs http.FileSystem, path string) (source.Driver, error) {
	var d driver
	if err := d.Init(fs, path); err != nil {
		return nil, err
	}
	return &d, nil
}

// Open completes the implementetion of source.Driver interface. Other methods
// are implemented by the embedded PartialDriver struct.
func (d *driver) Open(url string) (source.Driver, error) {
	return nil, errors.New("open() cannot be called on the httpfs passthrough driver")
}

View on GitHub (pinned to 01a9643f14)