ory/hydra · error

DSN scheme yugabyte:// declares a YugabyteDB database but th

Error message

DSN scheme yugabyte:// declares a YugabyteDB database but the server is not YugabyteDB. Server reported: %q. Use a DSN scheme matching the actual server, or point the service at a YugabyteDB cluster.

What it means

checkDialect detects YugabyteDB by a version-marker substring. When the DSN scheme is yugabyte:// but version() does not contain the YugabyteDB marker, this error is returned so the service does not apply Yugabyte-specific migrations to a non-Yugabyte server. Note the check also depends on pop.DialectSupported(dbal.DriverYugabyteDB); if that dialect is unsupported, VerifyDialect skips verification entirely.

Source

Thrown at oryx/popx/dialect_check.go:55

const (
	namePostgres = "postgres"

	// yugabyteVersionMarker identifies a YugabyteDB server in the output of
	// SELECT version() (e.g. "PostgreSQL 11.2-YB-2025.2.4.0-b122 ...").
	yugabyteVersionMarker = "-YB-"
)

func checkDialect(declared, version string, yugabyteDialectSupported bool) error {
	detectedCockroach := strings.Contains(version, "CockroachDB")
	detectedYugabyte := strings.Contains(version, yugabyteVersionMarker)
	switch {
	case declared == dbal.DriverCockroachDB && !detectedCockroach:
		return errors.Errorf(
			"DSN scheme cockroach:// declares a CockroachDB database but the server is not CockroachDB. Server reported: %q. Use a postgres:// DSN, or point the service at a CockroachDB cluster.",
			firstLine(version),
		)
	case declared == dbal.DriverYugabyteDB && !detectedYugabyte:
		return errors.Errorf(
			"DSN scheme yugabyte:// declares a YugabyteDB database but the server is not YugabyteDB. Server reported: %q. Use a DSN scheme matching the actual server, or point the service at a YugabyteDB cluster.",
			firstLine(version),
		)
	case declared == namePostgres && detectedCockroach:
		return errors.Errorf(
			"DSN scheme postgres:// declares a PostgreSQL database but the server is CockroachDB. Replace the scheme with cockroach:// so that the service picks the correct migrations and SQL dialect. Server reported: %q",
			firstLine(version),
		)
	case declared == namePostgres && detectedYugabyte && yugabyteDialectSupported:
		return errors.Errorf(
			"DSN scheme postgres:// declares a PostgreSQL database but the server is YugabyteDB. Replace the scheme with yugabyte:// (supported in Ory Enterprise License builds) so that the service picks the correct migrations. Server reported: %q",
			firstLine(version),
		)
	}
	return nil
}

func firstLine(s string) string {

View on GitHub (pinned to 4174065ffb)

Solutions

1. Point the DSN at a real YugabyteDB cluster
2. If the server is PostgreSQL or CockroachDB, change the scheme to postgres:// or cockroach:// respectively
3. Verify the actual server: psql '<DSN>' -c 'SELECT version()' and look for the Yugabyte marker
4. If it IS YugabyteDB but fails, check the version string format against yugabyteVersionMarker and upgrade the library

Example fix

// before
dsn := "yugabyte://user@pg-host:5432/db" // host is PostgreSQL
// after
dsn := "postgres://user@pg-host:5432/db"

func ensureYugabyteDSN(dsn string, conn *pop.Connection) error {
    var version string
    if err := conn.RawQuery("SELECT version()").First(&version); err != nil {
        return err
    }
    if strings.HasPrefix(dsn, "yugabyte://") && !strings.Contains(version, "YugabyteDB") {
        return fmt.Errorf("DSN declares yugabyte but server reports: %s", version)
    }
    return nil
}

if err := VerifyDialect(ctx, conn, dsn); err != nil && strings.Contains(err.Error(), "declares a YugabyteDB database") {
    return fmt.Errorf("align DSN scheme with actual server: %w", err)
}

When it happens

Trigger: Connecting with a yugabyte:// DSN to a plain PostgreSQL or CockroachDB server; or using yugabyte:// against an older YugabyteDB build whose version() string lacks the marker while the Yugabyte dialect is supported.

Common situations: Scheme swapped in config templating; pointing at a PG dev database with a Yugabyte production config; YugabyteDB version upgrade/downgrade changing the version string; running on a build where Yugabyte dialect support is compiled in but the server is not Yugabyte.

Related errors

• DSN scheme cockroach:// declares a CockroachDB database but
• unsupported dialect
• could not query database version to verify dialect
• DSN scheme postgres:// declares a PostgreSQL database but th
• %s

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/6c762c8c1e348ee9. Report an issue: GitHub.