multica-ai/multica · error

--cutoff is required; use the hosted deployment time of the

Error message

--cutoff is required; use the hosted deployment time of the Codex usage normalization fix

What it means

Config validation error from the backfill tool: --cutoff was not supplied at all. The cutoff defines which Codex task_usage rows are eligible for correction (rows last touched before the cutoff), and it is mandatory because the tool refuses to guess a correction boundary — it must be the hosted deployment time of the Codex usage normalization fix.

Source

Thrown at server/cmd/backfill_codex_usage_cache/main.go:161

	rollupFrom, rollupTo := rollupWindow(updateStartedAt, updateFinishedAt)
	var rollupRows int64
	if err := pool.QueryRow(ctx,
		`SELECT rollup_task_usage_hourly_window($1::timestamptz, $2::timestamptz)`,
		rollupFrom, rollupTo,
	).Scan(&rollupRows); err != nil {
		return fmt.Errorf("rebuild hourly rollup for update window %s..%s: %w",
			rollupFrom.Format(time.RFC3339), rollupTo.Format(time.RFC3339), err)
	}
	slog.Info("hourly rollup rebuilt",
		"from", rollupFrom.Format(time.RFC3339),
		"to", rollupTo.Format(time.RFC3339),
		"rows_touched", rollupRows)
	return nil
}

func (cfg *config) parseAndValidate(now time.Time) error {
	if cfg.cutoffRaw == "" {
		return fmt.Errorf("--cutoff is required; use the hosted deployment time of the Codex usage normalization fix")
	}
	cutoff, err := time.Parse(time.RFC3339, cfg.cutoffRaw)
	if err != nil {
		return fmt.Errorf("parse --cutoff as RFC3339: %w", err)
	}
	cutoff = cutoff.UTC()
	if !cutoff.Before(now) {
		return fmt.Errorf("--cutoff must be before now; refusing a future cutoff because it could double-subtract already-normalized rows")
	}
	if cfg.batchSize <= 0 {
		return fmt.Errorf("--batch-size must be positive")
	}
	cfg.cutoff = cutoff
	return nil
}

func loadDryRunSummary(ctx context.Context, pool *pgxpool.Pool, cfg config) ([]summaryRow, totals, error) {
	const query = `

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Add --cutoff <RFC3339 timestamp> set to the hosted deployment time of the Codex usage normalization fix.
2. Run the tool once without --execute to see the dry-run summary for that cutoff before applying.

Example fix

# before
./backfill_codex_usage_cache
# --cutoff is required; ...

# after
./backfill_codex_usage_cache --cutoff 2026-06-01T12:00:00Z  # dry-run first, then add --execute

# Guard in the runbook
CUTOFF=${CUTOFF:?"--cutoff (RFC3339, hosted deploy time of the Codex fix) is required"}
./backfill_codex_usage_cache --cutoff "$CUTOFF"

When it happens

Trigger: Invoking backfill_codex_usage_cache with no --cutoff flag, or with the flag name misspelled so it is never parsed.

Common situations: Copy-pasting the command from a runbook that omitted the flag; assuming the tool defaults the cutoff to 'now'; flag typos like -cutoff or --cuttoff being silently treated as unknown and ignored.

Related errors

• --batch-size must be positive
• parse --cutoff as RFC3339: %w
• --cutoff must be before now; refusing a future cutoff becaus
• --%s, --%s-stdin, and --%s-file are mutually exclusive; pick
• --%s-file: path must not be empty

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/2de66b15e4ada8a3. Report an issue: GitHub.