{"record":{"id":"54b195439f28c166","repo":"golang-migrate/migrate","slug":"failed-to-init-driver-with-relative-path-q-w","errorCode":null,"errorMessage":"failed to init driver with relative path %q: %w","messagePattern":"failed to init driver with relative path %q: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"source/pkger/pkger.go","lineNumber":45,"sourceCode":"// migrations must be added to the global pkger.Pkger instance by calling\n// pkger.Apply. Refer to Pkger documentation for more information.\nfunc (p *Pkger) Open(url string) (source.Driver, error) {\n\tu, err := stdurl.Parse(url)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// wrap pkger to implement http.FileSystem.\n\tfs := fsFunc(func(name string) (http.File, error) {\n\t\tf, err := pkger.Open(name)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\treturn f.(http.File), nil\n\t})\n\n\tif err := p.Init(fs, u.Path); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to init driver with relative path %q: %w\", u.Path, err)\n\t}\n\n\treturn p, nil\n}\n\n// WithInstance returns a source.Driver that is backed by an instance of\n// pkging.Pkger. The relative location of migrations is indicated by path. The\n// path must exist on the pkging.Pkger instance for the driver to initialize\n// successfully.\nfunc WithInstance(instance pkging.Pkger, path string) (source.Driver, error) {\n\tif instance == nil {\n\t\treturn nil, fmt.Errorf(\"expected instance of pkging.Pkger\")\n\t}\n\n\t// wrap pkger to implement http.FileSystem.\n\tfs := fsFunc(func(name string) (http.File, error) {\n\t\tf, err := instance.Open(name)\n\t\tif err != nil {","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/golang-migrate/migrate/blob/01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a/source/pkger/pkger.go#L27-L63","documentation":"golang-migrate's pkger source driver wraps a go-pkger embedded filesystem. Open(url) parses the URL and calls Init on the driver with the URL's path; if Init fails (e.g. the path does not exist inside the embedded pkger filesystem), the underlying error is wrapped as \"failed to init driver with relative path %q: %w\".","triggerScenarios":"Calling migrate.New with a pkger:// URL whose embedded path does not exist inside the go-pkger package, e.g. source/pkger!migrations not included at build time, or a typo'd subdirectory in the URL path.","commonSituations":"Using pkger to embed migrations but forgetting to run the pkger tool before building, migrations living in a directory different from the URL path, or renaming the migrations folder without updating the URL.","solutions":["Regenerate the pkger bundle (pkger -include /migrations) so the path exists in the embedded filesystem, then rebuild.","Verify the path component of the pkger URL exactly matches an existing directory in the pkger instance (case-sensitive).","Inspect the wrapped error (errors.Unwrap / %w chain) from p.Init to see the root cause (e.g. file does not exist).","Ensure migrations were embedded before running tests in CI; pkger assets are only present after generation."],"exampleFix":"// before (URL points to missing dir)\nm, err := migrate.New(\"pkger:///migrats\", \"postgres://...\")\n// after\ngo run github.com/markbates/pkger/cmd/pkger -include /migrations\nm, err := migrate.New(\"pkger:///migrations\", \"postgres://...\")","handlingStrategy":"validation","validationCode":"// before building the URL, confirm the embedded path exists\nf, err := pkger.Open(\"/migrations\")\nif err != nil {\n\treturn fmt.Errorf(\"pkger path /migrations not embedded: %w\", err)\n}\nf.Close()\nm, err := migrate.New(\"pkger:///migrations\", dsn)","typeGuard":null,"tryCatchPattern":"if err != nil {\n\tif strings.Contains(err.Error(), \"failed to init driver with relative path\") {\n\t\t// inspect errors.Unwrap(err) for the root cause; fix embed path and rebuild\n\t}\n\treturn err\n}","preventionTips":["Run the pkger generator in your build pipeline before compiling/running migrations.","Add a startup check that pkger.Open(migrationsDir) succeeds.","Keep the pkger URL path and the embedded directory in one shared constant."],"tags":["go","migrate","pkger","embedded-fs","path"],"backgroundTag":"migration-path-not-found","analyzedSha":"01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a","analyzedAt":"2026-09-02T19:38:29.671Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}