{"record":{"id":"a5cc6bf2aba5a300","repo":"golang-migrate/migrate","slug":"failed-to-init-driver-with-path-s-w","errorCode":null,"errorMessage":"failed to init driver with path %s: %w","messagePattern":"failed to init driver with path (.+?): %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"source/iofs/iofs.go","lineNumber":24,"sourceCode":"\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"io/fs\"\n\t\"path\"\n\t\"strconv\"\n\n\t\"github.com/golang-migrate/migrate/v4/source\"\n)\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","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/golang-migrate/migrate/blob/01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a/source/iofs/iofs.go#L6-L42","documentation":"New wraps any error returned by the iofs driver's Init (the underlying iofs passthrough driver initialization) with context about the path: 'failed to init driver with path %s: %w'. It signals that the given io/fs filesystem plus relative path could not be initialized — most commonly because the path does not exist or is not a directory within the provided fs.FS.","triggerScenarios":"Calling iofs.New(fsys, path) where fs.Stat(fsys, path) fails or the entry is not a directory — e.g. embedding migrations via embed.FS with an incorrect path prefix (embed paths do not include the 'migrations' directory unless embedded as such).","commonSituations":"embed.FS path confusion (//go:embed migrations yields entries prefixed 'migrations/' or not, depending on embed pattern); typo'd path; passing a file instead of a directory; using os.DirFS with a wrong root.","solutions":["Verify the path exists inside the fs.FS: fs.Stat(fsys, path) and confirm it is a directory before calling New","With embed.FS, check the //go:embed pattern — embed 'migrations/*' requires passing 'migrations' as path, while embedding into a migrations package may need \".\"","Print available entries with fs.ReadDir(fsys, \".\") to see the actual structure and correct the path","Read the wrapped error (%v on the result) for the root cause, e.g. 'file does not exist'"],"exampleFix":"// before\n//go:embed migrations\nvar fsys embed.FS\nd, err := iofs.New(fsys, \"migrations\") // ok if pattern is 'migrations'\n// if pattern is 'migrations/*.sql' inside package migrations:\nd, err := iofs.New(fsys, \".\")","handlingStrategy":"validation","validationCode":"func mustDir(fsys fs.FS, path string) error {\n    fi, err := fs.Stat(fsys, path)\n    if err != nil {\n        return fmt.Errorf(\"path %q in fs: %w\", path, err)\n    }\n    if !fi.IsDir() {\n        return fmt.Errorf(\"%q is not a directory\", path)\n    }\n    entries, _ := fs.ReadDir(fsys, path)\n    if len(entries) == 0 {\n        return fmt.Errorf(\"%q contains no migration files\", path)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"d, err := iofs.New(fsys, \"migrations\")\nif err != nil {\n    var perr *fs.PathError\n    if errors.As(err, &perr) {\n        return fmt.Errorf(\"bad migrations path %q: %w\", perr.Path, err)\n    }\n    return err\n}","preventionTips":["Check the //go:embed pattern matches how you reference the path (embedded prefix vs \".\")","Debug embedded layout with fs.ReadDir(fsys, \".\") in a unit test","Pass directories, not files, as the path","Keep the embed directive and iofs.New path in the same package and tested together"],"tags":["iofs","embed","filesystem","path"],"backgroundTag":"file-not-found","analyzedSha":"01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a","analyzedAt":"2026-09-02T19:38:29.671Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}