What causes "Could not create driver" in ory/hydra?

Inspect the wrapped cause printed below this message (errors.Wrap preserves the original driver.New error) and fix the underlying connection problem.

ory/hydra · error

Could not create driver

Error message

Could not create driver

What it means

The Hydra janitor CLI constructs a SQL driver from the -e/--environment (DSN) or -c/--config flags and calls driver.New. This wrapped error is returned when driver.New fails, meaning the persister could not be initialized — almost always a bad or unreachable DSN or an unsupported/missing driver connection scheme.

Source

Thrown at cmd/cli/handler_janitor.go:123

	notAfter := time.Now()

	if keepYounger := flagx.MustGetDuration(cmd, KeepIfYounger); keepYounger > 0 {
		notAfter = notAfter.Add(-keepYounger)
	}

	if !flagx.MustGetBool(cmd, ReadFromEnv) && len(flagx.MustGetStringSlice(cmd, Config)) == 0 {
		co = append(co, configx.WithValue(config.KeyDSN, args[0]))
	}

	do := append(dOpts,
		driver.DisableValidation(),
		driver.DisablePreloading(),
		driver.WithConfigOptions(co...),
	)

	d, err := driver.New(ctx, do...)
	if err != nil {
		return errors.Wrap(err, "Could not create driver")
	}

	if len(d.Config().DSN()) == 0 {
		//lint:ignore ST1005 formatted error string used in CLI output
		return fmt.Errorf("%s\n%s\n%s\n", cmd.UsageString(),
			"When using flag -e, environment variable DSN must be set.",
			"When using flag -c, the dsn property should be set.")
	}

	p := d.Persister()

	limit := flagx.MustGetInt(cmd, Limit)
	batchSize := flagx.MustGetInt(cmd, BatchSize)

	var routineFlags []string

	if flagx.MustGetBool(cmd, OnlyTokens) {
		routineFlags = append(routineFlags, OnlyTokens)

View on GitHub (pinned to 4174065ffb)

Solutions

Inspect the wrapped cause printed below this message (errors.Wrap preserves the original driver.New error) and fix the underlying connection problem.
Verify the DSN set via -e flag or DSN environment variable is well-formed and reachable: `hydra janitor -e "postgres://user:pass@host:5432/db?sslmode=disable"`.
Confirm the database is running and network-reachable from where the CLI runs (docker network, VPN, security groups).
Test the same DSN with `hydra serve` or psql/mysql client to isolate janitor-specific config issues.

Example fix

// before
hydra janitor -c bad-config.yml

// after
DSN="postgres://hydra:secret@localhost:5432/hydra?sslmode=disable" hydra janitor -e "$DSN" --cleanup-grace-period 24h

Defensive patterns

Strategy: try-catch

Validate before calling

if os.Getenv("DSN") == "" && config.DSN == "" {
    return fmt.Errorf("janitor requires a DSN via -e flag or DSN env var")
}

Try / catch

if err := cmd.Run(); err != nil {
    var uerr *usageError
    if errors.As(err, &uerr) {
        fmt.Fprintln(os.Stderr, uerr.Usage())
    }
    log.Fatalf("janitor failed: %+v", err) // print full stack to see wrapped driver.New cause
}

Prevention

Validate the DSN with a connectivity check (ping/SELECT 1) before running janitor in CI.
Keep the DSN scheme prefix intact (postgres://, mysql://).
Source .env files before invoking the CLI.
Test the DSN with `hydra serve` or a native DB client to isolate network issues.

When it happens

Trigger: Running `hydra janitor` where driver.New(ctx, do...) fails: malformed DSN, unsupported scheme (missing postgres/mysql driver registration), or invalid driver config options passed via WithConfigOptions.

Common situations: DSN env var pointing at a database that is down or unreachable; DSN missing the connection scheme (e.g. 'postgres://' prefix dropped); running janitor with no -e flag so DSN is empty (see the follow-up usage error); wrong credentials so the driver fails its connection check.

Related errors

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