Value for --batch-size must not be greater than value for --

Error message

Value for --batch-size must not be greater than value for --limit

What it means

Janitor deletes in batches of --batch-size until --limit rows are removed; a batch size larger than the limit is inconsistent with that paging contract, so Args rejects it with this formatted CLI error.

Source

Thrown at cmd/cli/handler_janitor.go:74

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

func (j *JanitorHandler) RunE(cmd *cobra.Command, args []string) error {
	return purge(cmd, args, j.dOpts)
}

func purge(cmd *cobra.Command, args []string, dOpts []driver.OptionsModifier) error {
	ctx := cmd.Context()

	co := []configx.OptionModifier{
		configx.WithFlags(cmd.Flags()),
		configx.SkipValidation(),
	}

View on GitHub (pinned to 4174065ffb)

Solutions

Set --limit >= --batch-size, e.g. --limit 500 --batch-size 100.
Or simply raise --limit if you actually want more rows deleted per run.
Or lower --batch-size to match the intended per-run cap.
Align both values in the CronJob manifest/script in one place.

Example fix

// before
hydra janitor $DSN --tokens --limit 100 --batch-size 500

// after
hydra janitor $DSN --tokens --limit 500 --batch-size 100

Defensive patterns

Strategy: validation

Validate before calling

if [ "$BATCH" -gt "$LIMIT" ]; then
  echo "--batch-size must not exceed --limit" >&2; exit 1
fi

Prevention

Define limit and batch-size together in one config variable pair.
Convention: batch-size = limit/5 or a fixed 100, always <= limit.
Change both flags together when tuning janitor throughput.
Add a CI check validating the relationship in manifests.

When it happens

Trigger: Running `hydra janitor ... --batch-size 500 --limit 100` (batchSize > limit).

Common situations: Tuning one flag without the other in a scheduled job; copying examples where batch-size default (100) exceeds a small custom limit; confusion about which flag bounds the other.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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