{"record":{"id":"50f989c09d6d3a3d","repo":"plandex-ai/plandex","slug":"error-creating-migration-instance-v","errorCode":null,"errorMessage":"error creating migration instance: %v","messagePattern":"error creating migration instance: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"app/server/db/db.go","lineNumber":125,"sourceCode":"}\n\nfunc migrationsUp(dir string) error {\n\tif Conn == nil {\n\t\treturn errors.New(\"db not initialized\")\n\t}\n\n\tdriver, err := postgres.WithInstance(Conn.DB, &postgres.Config{})\n\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error creating postgres driver: %v\", err)\n\t}\n\n\tm, err := migrate.NewWithDatabaseInstance(\n\t\t\"file://\"+dir,\n\t\t\"postgres\", driver)\n\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error creating migration instance: %v\", err)\n\t}\n\n\t// Uncomment below (and update migration version) to reset migration state to a specific version after a failure\n\t// if os.Getenv(\"GOENV\") == \"development\" {\n\t// \tmigrateVersion := 2025052900\n\t// \tif err := m.Force(migrateVersion); err != nil {\n\t// \t\treturn fmt.Errorf(\"error forcing migration version: %v\", err)\n\t// \t}\n\t// }\n\n\t// Uncomment below to run down migrations (RESETS DATABASE!!)\n\t// if os.Getenv(\"GOENV\") == \"development\" {\n\t// \terr = m.Down()\n\t// \tif err != nil {\n\t// \t\tif err == migrate.ErrNoChange {\n\t// \t\t\tlog.Println(\"no migrations to run down\")\n\t// \t\t} else {\n\t// \t\t\treturn fmt.Errorf(\"error running down migrations: %v\", err)","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/plandex-ai/plandex/blob/e2d772072efadbe41d2946d97d79be55532dbab5/app/server/db/db.go#L107-L143","documentation":"After the postgres driver is created, migrationsUp calls migrate.NewWithDatabaseInstance to bind the file:// migrations directory to that driver. This error wraps failure of that binding — almost always a bad migrations source URL (missing directory) or driver misconfiguration.","triggerScenarios":"MigrationsUp/MigrationsUpWithDir where the dir passed does not exist, is not an absolute/valid file:// path, or contains unparseable migration filenames (bad naming convention, duplicate versions).","commonSituations":"Deployments where the migrations folder wasn't copied into the image; running from a working directory where the relative path doesn't resolve; a renamed or hand-edited migration file breaking the version naming scheme.","solutions":["Verify the migrations directory exists at the resolved file:// path and is embedded/copied into the deployment","Use an absolute path (filepath.Abs(dir)) or MigrationsUpWithDir with an explicit dir","Check migration filenames match golang-migrate's NNNN_description.up/down.sql convention","Inspect the wrapped %v error for the exact source-URL or parse failure"],"exampleFix":"// before\nm, err := migrate.NewWithDatabaseInstance(\"file://\"+dir, \"postgres\", driver)\n// after\nabsDir, _ := filepath.Abs(dir)\nif _, statErr := os.Stat(absDir); statErr != nil {\n    return fmt.Errorf(\"migrations dir missing: %w\", statErr)\n}\nm, err := migrate.NewWithDatabaseInstance(\"file://\"+absDir, \"postgres\", driver)","handlingStrategy":"validation","validationCode":"absDir, err := filepath.Abs(dir)\nif err != nil {\n    return fmt.Errorf(\"bad migrations dir: %v\", err)\n}\nentries, err := os.ReadDir(absDir)\nif err != nil || len(entries) == 0 {\n    return fmt.Errorf(\"migrations dir missing or empty: %s\", absDir)\n}","typeGuard":null,"tryCatchPattern":"if err := MigrationsUp(); err != nil {\n    if strings.Contains(err.Error(), \"error creating migration instance\") {\n        log.Printf(\"check migrations dir path and file naming: %v\", err)\n    }\n    return err\n}","preventionTips":["Copy the migrations directory into container images (don't rely on host paths)","Use absolute paths resolved via filepath.Abs for the file:// source URL","Keep migration filenames in the strict NNNN_description.up/down.sql format","Smoke-test migrations in CI against a throwaway database"],"tags":["migrations","golang-migrate","filesystem","configuration"],"backgroundTag":"migration-instance-creation-failed","analyzedSha":"e2d772072efadbe41d2946d97d79be55532dbab5","analyzedAt":"2026-09-05T20:56:53.631Z","contentChangedAt":"2026-09-05T20:56:53.631Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}