expected to get the DSN as an argument, or the…

Error message

expected to get the DSN as an argument, or the "read-from-env" flag

What it means

CleanupSQL (the `hydra/cleanup sql` / Ory `cleanup sql` command) requires a database DSN. It either takes the DSN as a positional CLI argument or reads it from the environment when the `read-from-env` flag is set. This error is thrown when neither is supplied: no argument was passed and `--read-from-env` was not used.

Solutions

Pass the DSN as the single positional argument: `cleanup sql postgres://user:pass@host:5432/db?sslmode=disable`
Or add the `--read-from-env` flag so the DSN is read from the environment (DSN env var)
Ensure exactly one argument is given — 0 or more than 1 args both trigger this error
Check your job/deployment manifest that the command and args are wired correctly

Example fix

// before
cleanup sql
// after
cleanup sql --read-from-env
// or
cleanup sql postgres://user:pass@host:5432/db?sslmode=disable

Defensive patterns

Strategy: validation

Validate before calling

if len(os.Args) < 2 && !readFromEnv {
  log.Fatal(`expected the DSN as an argument or the "read-from-env" flag`)
}

Prevention

Always wrap the cleanup command in a wrapper that either passes the DSN or sets --read-from-env
In Kubernetes jobs, set --read-from-env and inject the DSN via env from a secret

When it happens

Trigger: Running the cleanup SQL command with no positional argument while `read-from-env` is false (or absent). E.g. `cleanup sql` alone, or passing zero args when the cobra command expects exactly one.

Common situations: Forgetting the DSN argument when scripting the cleanup command; running the binary manually instead of via a Helm/K8s job that normally injects the DSN; setting a DSN env var but forgetting the `--read-from-env` flag, so the env value is ignored.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of ory/kratos@b86338da04 (2026-09-07). Data as JSON: /api/errors/b72c5d997e86931f. Report an issue: GitHub.

Appendix: source

Thrown at cmd/cleanup/handler.go:34

	"github.com/ory/kratos/driver/config"
	"github.com/ory/x/flagx"
)

type CleanupHandler struct{}

func NewCleanupHandler() *CleanupHandler {
	return &CleanupHandler{}
}

func (h *CleanupHandler) CleanupSQL(cmd *cobra.Command, args []string) error {
	opts := []configx.OptionModifier{
		configx.WithFlags(cmd.Flags()),
		configx.SkipValidation(),
	}

	if !flagx.MustGetBool(cmd, "read-from-env") {
		if len(args) != 1 {
			return errors.New(`expected to get the DSN as an argument, or the "read-from-env" flag`)
		}
		opts = append(opts, configx.WithValue(config.ViperKeyDSN, args[0]))
	}

	d, err := driver.NewWithoutInit(
		cmd.Context(),
		cmd.ErrOrStderr(),
		driver.WithConfigOptions(opts...),
	)
	if len(d.Config().DSN(cmd.Context())) == 0 {
		return errors.New(`required config value "dsn" was not set`)
	} else if err != nil {
		return errors.Wrap(err, "An error occurred initializing cleanup")
	}

	err = d.Init(cmd.Context(), &contextx.Default{})
	if err != nil {
		return errors.Wrap(err, "An error occurred initializing cleanup")

View on GitHub (pinned to b86338da04)