plandex-ai/plandex · critical

error creating migration instance: %v

Error message

error creating migration instance: %v

What it means

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.

Source

Thrown at app/server/db/db.go:125

}

func migrationsUp(dir string) error {
	if Conn == nil {
		return errors.New("db not initialized")
	}

	driver, err := postgres.WithInstance(Conn.DB, &postgres.Config{})

	if err != nil {
		return fmt.Errorf("error creating postgres driver: %v", err)
	}

	m, err := migrate.NewWithDatabaseInstance(
		"file://"+dir,
		"postgres", driver)

	if err != nil {
		return fmt.Errorf("error creating migration instance: %v", err)
	}

	// Uncomment below (and update migration version) to reset migration state to a specific version after a failure
	// if os.Getenv("GOENV") == "development" {
	// 	migrateVersion := 2025052900
	// 	if err := m.Force(migrateVersion); err != nil {
	// 		return fmt.Errorf("error forcing migration version: %v", err)
	// 	}
	// }

	// Uncomment below to run down migrations (RESETS DATABASE!!)
	// if os.Getenv("GOENV") == "development" {
	// 	err = m.Down()
	// 	if err != nil {
	// 		if err == migrate.ErrNoChange {
	// 			log.Println("no migrations to run down")
	// 		} else {
	// 			return fmt.Errorf("error running down migrations: %v", err)

View on GitHub (pinned to e2d772072e)

Solutions

1. Verify the migrations directory exists at the resolved file:// path and is embedded/copied into the deployment
2. Use an absolute path (filepath.Abs(dir)) or MigrationsUpWithDir with an explicit dir
3. Check migration filenames match golang-migrate's NNNN_description.up/down.sql convention
4. Inspect the wrapped %v error for the exact source-URL or parse failure

Example fix

// before
m, err := migrate.NewWithDatabaseInstance("file://"+dir, "postgres", driver)
// after
absDir, _ := filepath.Abs(dir)
if _, statErr := os.Stat(absDir); statErr != nil {
    return fmt.Errorf("migrations dir missing: %w", statErr)
}
m, err := migrate.NewWithDatabaseInstance("file://"+absDir, "postgres", driver)

absDir, err := filepath.Abs(dir)
if err != nil {
    return fmt.Errorf("bad migrations dir: %v", err)
}
entries, err := os.ReadDir(absDir)
if err != nil || len(entries) == 0 {
    return fmt.Errorf("migrations dir missing or empty: %s", absDir)
}

if err := MigrationsUp(); err != nil {
    if strings.Contains(err.Error(), "error creating migration instance") {
        log.Printf("check migrations dir path and file naming: %v", err)
    }
    return err
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• error getting plan current branch: %v
• error creating postgres driver: %v
• error running migrations: %v
• error loading accounts: %v
• error resolving org: %v

AI-assisted analysis of plandex-ai/plandex@e2d772072e (2026-09-05). Data as JSON: /api/errors/50f989c09d6d3a3d. Report an issue: GitHub.