ory/hydra · error

Janitor requires at least one of --tokens, --requests or --g

Error message

Janitor requires at least one of --tokens, --requests or --grants to be set

What it means

Janitor deletes expired entities but only the categories you opt into. Args validates that at least one of --tokens, --requests, or --grants is set; otherwise it would run a no-op sweep, so it prints usage and returns this error.

Source

Thrown at cmd/cli/handler_janitor.go:61

	}
}

func (*JanitorHandler) Args(cmd *cobra.Command, args []string) error {
	if len(args) == 0 &&
		!flagx.MustGetBool(cmd, ReadFromEnv) &&
		len(flagx.MustGetStringSlice(cmd, Config)) == 0 {

		fmt.Printf("%s\n", cmd.UsageString())
		//lint:ignore ST1005 formatted error string used in CLI output
		return fmt.Errorf("%s\n%s\n%s\n",
			"A DSN is required as a positional argument when not passing any of the following flags:",
			"- Using the environment variable with flag -e, --read-from-env",
			"- Using the config file with flag -c, --config")
	}

	if !flagx.MustGetBool(cmd, OnlyTokens) && !flagx.MustGetBool(cmd, OnlyRequests) && !flagx.MustGetBool(cmd, OnlyGrants) {
		//lint:ignore ST1005 formatted error string used in CLI output
		return fmt.Errorf("%s\n%s\n", cmd.UsageString(),
			"Janitor requires at least one of --tokens, --requests or --grants to be set")
	}

	limit := flagx.MustGetInt(cmd, Limit)
	batchSize := flagx.MustGetInt(cmd, BatchSize)
	if limit <= 0 || batchSize <= 0 {
		//lint:ignore ST1005 formatted error string used in CLI output
		return fmt.Errorf("%s\n%s\n", cmd.UsageString(),
			"Values for --limit and --batch-size should both be greater than 0")
	}
	if batchSize > limit {
		//lint:ignore ST1005 formatted error string used in CLI output
		return fmt.Errorf("%s\n%s\n", cmd.UsageString(),
			"Value for --batch-size must not be greater than value for --limit")
	}

	return nil
}

View on GitHub (pinned to 4174065ffb)

Solutions

1. Add the desired scope flags: `hydra janitor <dsn> --tokens --requests --grants`.
2. If you only intend one category, pass just that flag, e.g. `--tokens`.
3. Update CronJob/deployment manifests to include the flags.
4. Check flags: newer versions accept --grants; older ones only --tokens/--requests — use flags your version supports.

Example fix

// before
hydra janitor $DSN

// after
hydra janitor $DSN --tokens --requests --grants

# Ensure at least one scope flag present:
case "$*" in
  *--tokens*|*--requests*|*--grants*) ;;
  *) echo "janitor needs at least one of --tokens/--requests/--grants" >&2; exit 1 ;;
esac

When it happens

Trigger: Running `hydra janitor <dsn>` without any of --tokens, --requests, --grants (or --only-tokens/--only-requests/--only-grants booleans) set.

Common situations: Copying an old janitor command that predates the flags; a scheduled job losing its flags after a manifest edit; assuming janitor clears everything by default.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• A DSN is required as a positional argument when not passing
• Values for --limit and --batch-size should both be greater t
• Value for --batch-size must not be greater than value for --
• When using flag -e, environment variable DSN must be set. Wh
• Could not create driver

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