ory/hydra · error

DSN scheme postgres:// declares a PostgreSQL database but th

Error message

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.

What it means

VerifyDialect distinguishes PostgreSQL, CockroachDB, and YugabyteDB, which all speak the Postgres wire protocol. When the DSN is declared as postgres:// but SELECT version() reports a CockroachDB server, checkDialect (oryx/popx/dialect_check.go:59) throws this error to prevent the wrong migrations and SQL dialect from being silently applied. Running with the wrong dialect can produce broken schemas.

Source

Thrown at oryx/popx/dialect_check.go:60

	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 {
	if i := strings.IndexByte(s, '\n'); i >= 0 {
		return s[:i]
	}
	return s
}

View on GitHub (pinned to 4174065ffb)

Solutions

1. Change the DSN scheme in your config/DSN from postgres:// to cockroach:// so the service selects CockroachDB migrations and dialect
2. Verify you are connecting to the intended server: check host, port, and that SELECT version() matches the expected database
3. If the server really is CockroachDB but you need Postgres semantics, provision an actual PostgreSQL instance instead

Example fix

// before
DSN=postgres://user:pass@roach-host:26257/defaultdb?sslmode=disable
// after
DSN=cockroach://user:pass@roach-host:26257/defaultdb?sslmode=disable

// before connecting, check the server matches the declared scheme
var version string
if err := conn.RawQuery("SELECT version()").First(&version); err != nil { return err }
if strings.Contains(version, "CockroachDB") && conn.Dialect.Name() == "postgres" {
    return errors.New("DSN scheme must be cockroach:// for this server")
}

if err := popx.VerifyDialect(ctx, conn); err != nil {
    log.Fatalf("dialect verification failed: %v", err)
}

When it happens

Trigger: Calling VerifyDialect(ctx, conn) where conn's DSN scheme is postgres:// while the connected server's version() output contains "CockroachDB".

Common situations: Operator reuses a PostgreSQL DSN from another environment that actually points at a CockroachDB cluster; copy-pasted connection strings where only host/port were changed; managed-DB provisioning where a CockroachDB instance was created instead of Postgres.

Related errors

• DSN scheme postgres:// declares a PostgreSQL database but th
• unsupported DSN type
• The DSN connection string looks like a SQLite connection, bu
• invalid DSN: missing scheme separator
• invalid DSN: empty scheme

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