ory/hydra · error

%s %s %s When using flag -e, environment variable DSN must

Error message

%s
%s
%s
 When using flag -e, environment variable DSN must be set. When using flag -c, the dsn property should be set.

What it means

After the driver is created successfully, the janitor checks whether a DSN is configured. If d.Config().DSN() is empty, it returns a usage error (formatted with cmd.UsageString()) telling the user they must supply the DSN either via the -e flag/environment variable or the dsn property in the -c config file.

Source

Thrown at cmd/cli/handler_janitor.go:127

	}

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

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

View on GitHub (pinned to 4174065ffb)

Solutions

1. Pass the DSN explicitly: `hydra janitor -e "postgres://user:pass@host:5432/db?sslmode=disable"`.
2. Export the DSN environment variable before running: `export DSN=... && hydra janitor`.
3. Add `dsn: postgres://...` to the YAML config passed with -c.
4. Run `hydra janitor` alone first — its output includes cmd.UsageString() showing the expected flags.

Example fix

// before
hydra janitor --read-from-env  # DSN never exported

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

if len(os.Getenv("DSN")) == 0 {
    return fmt.Errorf("DSN must be set (env var or -e flag) before running hydra janitor")
}

When it happens

Trigger: Running `hydra janitor` without the -e flag, with DSN unset, and with a -c config file that lacks the dsn property — so no DSN is present anywhere.

Common situations: Running janitor in a shell where the DSN env var wasn't exported (e.g. only set in a .env file that wasn't sourced); CI jobs invoking janitor without injecting secrets; config file pointing to a different environment that omits dsn.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• When using flag -e, environment variable DSN must be set. Wh
• A DSN is required as a positional argument when not passing
• Could not create driver
• you have to set the remote endpoint, try --help for details
• Janitor requires at least one of --tokens, --requests or --g

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