cache-replay: -trace and positive request/token/trace/respon

Error message

cache-replay: -trace and positive request/token/trace/response/verifier limits required

What it means

Fatal configuration error from cache-replay main(): a single combined guard over many flags failed. -trace must be non-empty and an absolute path; -max-requests in (0, maxReplayRequests]; -max-tokens > 0; -max-trace-bytes in (0, maxReplayTraceBytes]; -max-response-bytes in (0, 256MiB]; -provider-timeout in [1s, 1h]; -max-verifier-output-bytes in (0, 256MiB]; -verifier-timeout > 0; -max-schedule-drift > 0; -max-concurrency in (0, 1024]. fatalConfig means the process exits before any replay work.

Source

Thrown at cacheengine/cmd/cache-replay/main.go:219

	timeScale := flag.Float64("time-scale", 1, "trace timing multiplier; 1 preserves grounded timing")
	allowUngrounded := flag.Bool("allow-ungrounded-timing", false, "permit synthetic/per-partition schedules; evidence is not timing-faithful")
	allowEstimatedTokens := flag.Bool("allow-estimated-token-budget", false, "permit non-provider token estimates; input ceiling is not provider-grounded")
	maxResponseBytes := flag.Int64("max-response-bytes", 16<<20, "maximum retained provider response bytes/request")
	providerTimeout := flag.Duration("provider-timeout", 2*time.Minute, "hard timeout per provider request (1s-1h)")
	verifierPath := flag.String("verifier-command", "", "task verifier executable; receives one JSON object on stdin")
	verifierOutputBytes := flag.Int64("max-verifier-output-bytes", 16<<20, "maximum verifier JSON bytes/request")
	targetRate := flag.Float64("target", .97, "required request and token cache-hit rate")
	minEligible := flag.Int("min-requests", 100, "minimum eligible requests/provider")
	allowInsecureLoopback := flag.Bool("allow-insecure-loopback", false, "allow HTTP only for explicit loopback test base URLs")
	allowCustomBaseURL := flag.Bool("allow-custom-base-url", false, "confirm credentials may be sent to explicit custom HTTPS base URLs")
	verifierTimeout := flag.Duration("verifier-timeout", 5*time.Minute, "hard timeout per task-verifier invocation")
	flag.Var(&verifierArgs, "verifier-arg", "verifier argument; repeatable, no shell parsing")
	flag.Var(&verifierEnv, "verifier-env", "environment variable exposed to verifier; repeatable")
	flag.Var(&baseURLs, "base-url", "test/custom provider base URL as provider=https://host; repeatable")
	flag.Parse()

	if *tracePath == "" || !filepath.IsAbs(*tracePath) || *maxRequests <= 0 || *maxRequests > maxReplayRequests || *maxTokens <= 0 || *maxTraceBytes <= 0 || *maxTraceBytes > maxReplayTraceBytes || *maxResponseBytes <= 0 || *maxResponseBytes > 256<<20 || *providerTimeout < time.Second || *providerTimeout > time.Hour || *verifierOutputBytes <= 0 || *verifierOutputBytes > 256<<20 || *verifierTimeout <= 0 || *maxScheduleDrift <= 0 || *maxConcurrency <= 0 || *maxConcurrency > 1024 {
		fatalConfig(errors.New("cache-replay: -trace and positive request/token/trace/response/verifier limits required"))
	}
	if (*maxResponseBytes+*verifierOutputBytes)*int64(*maxConcurrency) > maxReplayInflightBytes {
		fatalConfig(fmt.Errorf("cache-replay: concurrent response and verifier buffers exceed %d bytes", maxReplayInflightBytes))
	}
	if len(baseURLs) > 0 && !*allowCustomBaseURL {
		fatalConfig(errors.New("cache-replay: custom base URLs require -allow-custom-base-url"))
	}
	records, traceSHA, err := readTrace(*tracePath, *maxTraceBytes, *maxRequests)
	if err != nil {
		fatalConfig(err)
	}
	limits := cachebench.ReplayLimits{
		MaxRequests: *maxRequests, MaxDeclaredBilledTokens: *maxTokens, MaxGap: *maxGap, MaxScheduleDrift: *maxScheduleDrift,
		MaxConcurrency:        *maxConcurrency,
		RequireGroundedTiming: !*allowUngrounded, RequireProviderTokens: !*allowEstimatedTokens,
	}
	preflight, err := cachebench.ValidateReplay(records, limits, *timeScale)
	if err != nil {

View on GitHub (pinned to 27d5a3981a)

Solutions

Make -trace an absolute path (prefix with $(realpath ...) or $PWD/)
Set every numeric flag positive and within ceilings; start from defaults and change one at a time
For concurrency above 1024 or larger buffers, you must reduce per-request sizes instead — the caps are hard limits
Run with -h to list all flags and their defaults, then re-issue the command

Example fix

# before
cache-replay -trace traces/t.jsonl -max-concurrency 2000

# after
cache-replay -trace "$PWD/traces/t.jsonl" -max-concurrency 1024

Defensive patterns

Strategy: validation

Validate before calling

func validReplayFlags(trace string, maxReq, maxTok, maxTrace, maxResp int64, timeout, vTimeout time.Duration, drift time.Duration, conc int) bool {
	return trace != "" && filepath.IsAbs(trace) &&
		maxReq > 0 && maxTok > 0 && maxTrace > 0 && maxResp > 0 && maxResp <= 256<<20 &&
		timeout >= time.Second && timeout <= time.Hour && vTimeout > 0 && drift > 0 &&
		conc > 0 && conc <= 1024
}

Prevention

Wrap the CLI in a shell function that realpath's the trace and clamps numerics before exec
Keep a known-good command template in the repo and diff against it when flags change

When it happens

Trigger: Passing a relative -trace path like ./trace.jsonl; leaving a numeric flag at 0 or negative; exceeding a ceiling such as -max-concurrency 2048 or -max-response-bytes above 256MiB; -provider-timeout 500ms; omitting -trace entirely.

Common situations: Copy-pasted command lines from another machine with different paths; default-zero flags someone assumed were optional; scaling concurrency up in CI and hitting the 1024 cap; scripting with unquoted relative paths.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/9495399c6a3aee64. Report an issue: GitHub.