{"record":{"id":"f9b0e9d2bc83ff5f","repo":"golang-migrate/migrate","slug":"database-driver-unknown-driver-v-forgotten-impo","errorCode":null,"errorMessage":"database driver: unknown driver %v (forgotten import?)","messagePattern":"database driver: unknown driver (.+?) \\(forgotten import\\?\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"database/driver.go","lineNumber":95,"sourceCode":"\n\t// Drop deletes everything in the database.\n\t// Note that this is a breaking action, a new call to Open() is necessary to\n\t// ensure subsequent calls work as expected.\n\tDrop() error\n}\n\n// Open returns a new driver instance.\nfunc Open(url string) (Driver, error) {\n\tscheme, err := iurl.SchemeFromURL(url)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tdriversMu.RLock()\n\td, ok := drivers[scheme]\n\tdriversMu.RUnlock()\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"database driver: unknown driver %v (forgotten import?)\", scheme)\n\t}\n\n\treturn d.Open(url)\n}\n\n// Register globally registers a driver.\nfunc Register(name string, driver Driver) {\n\tdriversMu.Lock()\n\tdefer driversMu.Unlock()\n\tif driver == nil {\n\t\tpanic(\"Register driver is nil\")\n\t}\n\tif _, dup := drivers[name]; dup {\n\t\tpanic(\"Register called twice for driver \" + name)\n\t}\n\tdrivers[name] = driver\n}\n","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/golang-migrate/migrate/blob/01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a/database/driver.go#L77-L113","documentation":"database.Open looks up the registered driver by URL scheme in a global registry populated via database.Register, which drivers trigger in their package init(). If no driver is registered for the URL's scheme, this \"unknown driver %v (forgotten import?)\" error is returned. The message hints at the usual cause: the driver package was never imported, so its init never ran.","triggerScenarios":"Calling migrate.Open/database.Open with a scheme (postgres, mysql, cassandra, etc.) whose driver package (e.g. _ \"github.com/golang-migrate/migrate/v4/database/postgres\") is not imported; misspelled or unsupported scheme in the URL.","commonSituations":"Blank imports removed by an IDE auto-cleanup; using a scheme name that doesn't match the registered one (e.g. \"postgresql://\" when only \"postgres\" is registered without a glue driver); switching drivers between dev and prod without updating imports; building with build tags excluding the driver.","solutions":["Add a blank import of the driver package: _ \"github.com/golang-migrate/migrate/v4/database/<driver>\".","Verify the URL scheme matches a registered driver name (check the driver package's init/Register call, e.g. \"postgres\", \"mysql\", \"cassandra\").","Check build tags/constraints aren't excluding the driver file from compilation, and that no import-cleanup removed the blank import."],"exampleFix":"// before\nimport (\n    \"github.com/golang-migrate/migrate/v4\"\n)\n// after\nimport (\n    _ \"github.com/golang-migrate/migrate/v4/database/postgres\"\n    _ \"github.com/golang-migrate/migrate/v4/source/file\"\n    \"github.com/golang-migrate/migrate/v4\"\n)","handlingStrategy":"try-catch","validationCode":"import (\n    _ \"github.com/golang-migrate/migrate/v4/database/postgres\"\n    _ \"github.com/golang-migrate/migrate/v4/source/file\"\n)","typeGuard":null,"tryCatchPattern":"m, err := migrate.Open(dsn)\nif err != nil {\n    if strings.Contains(err.Error(), \"unknown driver\") {\n        return fmt.Errorf(\"scheme %q has no registered driver; add the blank import for the driver package\", schemeOf(dsn))\n    }\n    return err\n}","preventionTips":["Always blank-import every driver and source package you use via URLs.","Keep driver imports in a dedicated imports.go file so IDE cleanups and linters don't remove them.","Confirm the URL scheme exactly matches the registered driver name (e.g. \"postgres\", not \"postgresql\", unless the glue package registers it).","Check build tags when drivers appear missing only in certain builds."],"tags":["driver-registry","import","configuration"],"backgroundTag":"unknown-driver-forgotten-import","analyzedSha":"01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a","analyzedAt":"2026-09-02T19:38:29.671Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}