plandex-ai/plandex · critical

error creating postgres driver: %v

Error message

error creating postgres driver: %v

What it means

migrationsUp uses golang-migrate's postgres.WithInstance to wrap the existing sqlx DB handle as a migration driver. This error wraps a failure in that wrapping step, typically because the underlying *sql.DB is unhealthy or already closed.

Source

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

		migrationsDir = os.Getenv("MIGRATIONS_DIR")
	}

	return migrationsUp(migrationsDir)
}

func MigrationsUpWithDir(dir string) error {
	return migrationsUp(dir)
}

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)
	// 	}
	// }

View on GitHub (pinned to e2d772072e)

Solutions

1. Check the wrapped %v error and ping the DB before running migrations (Conn.Ping())
2. If the pool is stale, re-run Connect/MustInitDb to rebuild Conn, then retry migrations
3. Ensure migrations run before any code closes the DB handle
4. Verify postgres is reachable and accepting connections

Example fix

// before
driver, err := postgres.WithInstance(Conn.DB, &postgres.Config{})
// after
if err := Conn.Ping(); err != nil {
    MustInitDb() // rebuild stale connection pool
}
driver, err := postgres.WithInstance(Conn.DB, &postgres.Config{})

if Conn == nil || Conn.DB == nil {
    return errors.New("db not initialized")
}
if err := Conn.Ping(); err != nil {
    return fmt.Errorf("db connection unhealthy before migrations: %v", err)
}

if err := MigrationsUp(); err != nil {
    if strings.Contains(err.Error(), "error creating postgres driver") {
        MustInitDb() // rebuild stale pool, then retry once
        return MigrationsUp()
    }
    return err
}

When it happens

Trigger: MigrationsUp/MigrationsUpWithDir called when Conn is non-nil but the pooled connection is closed/broken (postgres restart, idle timeout), or the postgres driver cannot configure itself against the handle.

Common situations: Running migrations in a job where the DB was closed earlier; database restarted between Connect and migrate; health-check race where Conn exists but ping fails.

Related errors

• error running migrations: %v
• error adding convo tokens: %v
• error checking settings: %v
• error creating migration instance: %v
• error validating org membership: %v

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