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.

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)

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 '%s' (forgotten import?)

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