{"record":{"id":"e533434598cb93fb","repo":"golang-migrate/migrate","slug":"open-cannot-be-called-on-the-iofs-passthrough-dr","errorCode":null,"errorMessage":"open() cannot be called on the iofs passthrough driver","messagePattern":"open\\(\\) cannot be called on the iofs passthrough driver","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"source/iofs/iofs.go","lineNumber":32,"sourceCode":")\n\ntype driver struct {\n\tPartialDriver\n}\n\n// New returns a new Driver from io/fs#FS and a relative path.\nfunc New(fsys fs.FS, path string) (source.Driver, error) {\n\tvar i driver\n\tif err := i.Init(fsys, path); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to init driver with path %s: %w\", path, err)\n\t}\n\treturn &i, nil\n}\n\n// Open is part of source.Driver interface implementation.\n// Open cannot be called on the iofs passthrough driver.\nfunc (d *driver) Open(url string) (source.Driver, error) {\n\treturn nil, errors.New(\"open() cannot be called on the iofs passthrough driver\")\n}\n\n// PartialDriver is a helper service for creating new source drivers working with\n// io/fs.FS instances. It implements all source.Driver interface methods\n// except for Open(). New driver could embed this struct and add missing Open()\n// method.\n//\n// To prepare PartialDriver for use Init() function.\ntype PartialDriver struct {\n\tmigrations *source.Migrations\n\tfsys       fs.FS\n\tpath       string\n}\n\n// Init prepares not initialized IoFS instance to read migrations from a\n// io/fs#FS instance and a relative path.\nfunc (d *PartialDriver) Init(fsys fs.FS, path string) error {\n\tentries, err := fs.ReadDir(fsys, path)","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/golang-migrate/migrate/blob/01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a/source/iofs/iofs.go#L14-L50","documentation":"The iofs package wraps an io/fs.FS as a migration source. Its driver's Open method is deliberately unimplemented — instances are created by WithInstance(fsys), not through the URL registry — so any call to Open returns this error. It exists only to complete the source.Driver interface.","triggerScenarios":"Calling Open on the driver returned by iofs.WithInstance; registering the iofs driver under a URL scheme and then invoking source.Open(\"iofs://...\").","commonSituations":"Trying to use embed.FS-based migrations through the URL-based migrate.New API instead of migrate.NewWithSourceInstance; wrapping the passthrough driver in another driver and delegating Open to it.","solutions":["Use iofs.WithInstance(fsys) (e.g. with an embed.FS) and pass the result via migrate.NewWithSourceInstance(\"iofs\", d, databaseURL).","When embedding PartialDriver in a custom driver, override Open with a real constructor that returns your driver for valid URLs.","Do not register the passthrough driver in the URL scheme registry."],"exampleFix":"// before\nm, err := migrate.New(\"iofs://embedded\", dsn)\n// after\nd, err := iofs.WithInstance(migrationsFS)\nm, err := migrate.NewWithSourceInstance(\"iofs\", d, dsn)","handlingStrategy":"validation","validationCode":"d, err := iofs.WithInstance(embeddedFS)\nif err != nil { return err }\nm, err := migrate.NewWithSourceInstance(\"iofs\", d, databaseURL)","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"iofs passthrough\") {\n    return fmt.Errorf(\"iofs drivers must be created with iofs.WithInstance, not Open\")\n}","preventionTips":["Use iofs.WithInstance + migrate.NewWithSourceInstance for embed.FS migrations instead of URL-based construction.","Never call Open on drivers built from PartialDriver passthroughs.","Override Open when embedding PartialDriver in your own driver."],"tags":["iofs","source-driver","misuse"],"backgroundTag":"driver-open-not-implemented","analyzedSha":"01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a","analyzedAt":"2026-09-02T19:38:29.671Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}