{"record":{"id":"b93ef1fad7c37b0e","repo":"hasura/graphql-engine","slug":"source-driver-unknown-driver-v-forgotten-import","errorCode":null,"errorMessage":"source driver: unknown driver %v (forgotten import?)","messagePattern":"source driver: unknown driver (.+?) \\(forgotten import\\?\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/migrate/source/driver.go","lineNumber":131,"sourceCode":"\tu, err := nurl.Parse(url)\n\tif err != nil {\n\t\treturn nil, errors.E(op, err)\n\t}\n\n\tif u.Scheme == \"\" {\n\t\treturn nil, errors.E(op, stderrors.New(\"source driver: invalid URL scheme\"))\n\t}\n\n\tdriversMu.RLock()\n\n\td, ok := drivers[u.Scheme]\n\n\tdriversMu.RUnlock()\n\n\tif !ok {\n\t\treturn nil, errors.E(\n\t\t\top,\n\t\t\tfmt.Errorf(\"source driver: unknown driver %v (forgotten import?)\", u.Scheme),\n\t\t)\n\t}\n\n\tif logger == nil {\n\t\tlogger = log.New()\n\t}\n\n\tdriver, err := d.Open(url, logger)\n\tif err != nil {\n\t\treturn driver, errors.E(op, err)\n\t}\n\n\treturn driver, nil\n}\n\n// Register globally registers a driver.\nfunc Register(name string, driver Driver) {\n\tdriversMu.Lock()","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/migrate/source/driver.go#L113-L149","documentation":"Returned by source.Open when the URL scheme of the migration source doesn't match any registered source driver. Drivers register themselves in a registry (with driversMu) keyed by scheme (e.g. 'file', 'hasuradb', 'postgres'), and an unknown scheme means the driver package was never imported — a common trap with Go's init()-based driver registration.","triggerScenarios":"Calling source.Open (directly or via migrate.NewMigrate/New) with a URL whose scheme has no registered driver, e.g. `foo://...`, or building a custom binary that imports cli/migrate but not cli/migrate/source/file or cli/migrate/database/hasuradb, so their init() registrations never run.","commonSituations":"Embedding the hasura CLI migrate API in your own Go program and forgetting the blank imports (`_ \"github.com/hasura/graphql-engine/cli/migrate/source/file\"`); typos in the source URL scheme; refactoring that drops a driver import.","solutions":["Add the missing driver import to the binary's entry point, usually as a blank import: `_ \".../cli/migrate/source/file\"` and `_ \".../cli/migrate/database/hasuradb\"`","Check the URL scheme passed to Open matches a registered driver exactly (file, hasuradb, postgres, ...)","If writing a custom driver, verify Register was called in its init() before Open"],"exampleFix":"// before\nimport \"github.com/hasura/graphql-engine/cli/migrate/source\"\nsrc, err := source.Open(u, logger) // unknown driver \"file\"\n\n// after\nimport (\n  _ \"github.com/hasura/graphql-engine/cli/migrate/source/file\"\n  _ \"github.com/hasura/graphql-engine/cli/migrate/database/hasuradb\"\n  \"github.com/hasura/graphql-engine/cli/migrate/source\"\n)\nsrc, err := source.Open(u, logger)","handlingStrategy":"validation","validationCode":"u, err := nurl.Parse(srcURL)\nif err != nil { return err }\nswitch u.Scheme {\ncase \"file\", \"hasuradb\", \"postgres\": // known schemes\n\tsrc, err := source.Open(u, logger)\n\tif err != nil { return err }\n\t_ = src\ndefault:\n\treturn fmt.Errorf(\"unsupported scheme %q\", u.Scheme)\n}","typeGuard":null,"tryCatchPattern":"if _, err := source.Open(u, logger); err != nil {\n    if strings.Contains(err.Error(), \"unknown driver\") {\n        // add blank driver imports and rebuild\n    }\n    return err\n}","preventionTips":["Always blank-import every driver package next to the Open call","Centralize driver imports in one registration file","Add a startup smoke test that opens each configured URL scheme"],"tags":["driver-registry","go-imports","migrations","hasura"],"backgroundTag":"unknown-driver-scheme","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}