ory/hydra · error

DSN scheme cockroach:// declares a CockroachDB database but

Error message

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.

What it means

checkDialect compares the declared DSN scheme with the server's version() output. When the DSN scheme is cockroach:// but the version string does not contain 'CockroachDB', the library refuses to run, because migrations and SQL dialect differ between PostgreSQL and CockroachDB. The %q is the server's reported version first line.

Source

Thrown at oryx/popx/dialect_check.go:50

		return errors.Wrap(err, "could not query database version to verify dialect")
	}
	return checkDialect(declared, version, pop.DialectSupported(dbal.DriverYugabyteDB))
}

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),
		)

View on GitHub (pinned to 4174065ffb)

Solutions

1. Point the DSN at a real CockroachDB cluster
2. If the server truly is PostgreSQL, change the scheme to postgres://
3. Verify with: psql '<DSN>' -c 'SELECT version()' and check for 'CockroachDB'
4. Fix config templating that injects the wrong scheme per environment

Example fix

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

func dsnSchemeMatchesServer(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, "cockroach://") && !strings.Contains(version, "CockroachDB") {
        return fmt.Errorf("DSN declares cockroach but server reports: %s", version)
    }
    return nil
}

if err := VerifyDialect(ctx, conn, dsn); err != nil && strings.Contains(err.Error(), "declares a CockroachDB database") {
    return fmt.Errorf("fix DSN scheme in config: %w", err)
}

When it happens

Trigger: Connecting VerifyDialect/migration manager with a cockroach:// DSN to a server that is actually PostgreSQL (or YugabyteDB or another PG-compatible fork).

Common situations: Copy-pasting a DSN and only swapping the scheme; a proxy/load balancer routing 'cockroach' DSNs to a plain Postgres instance; switching infrastructure but leaving the old DSN scheme in config.

Related errors

• DSN scheme yugabyte:// declares a YugabyteDB database but th
• 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/1cd1236cc23e4858. Report an issue: GitHub.