JuliusBrussee/caveman · error

cache-replay: custom base URLs require -allow-custom-base-ur

Error message

cache-replay: custom base URLs require -allow-custom-base-url

What it means

Fatal config error from cache-replay: at least one -base-url provider=https://host was supplied but -allow-custom-base-url was not set to true. Because custom base URLs determine where provider credentials are sent, the tool requires an explicit opt-in confirming you accept sending credentials to that host.

Source

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

	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 {
		fatalConfig(err)
	}
	target := cachebench.Target{RequestHitRate: *targetRate, TokenHitRate: *targetRate, MinEligibleRequest: *minEligible}
	if err := cachebench.ValidateReplayTarget(records, target); err != nil {
		fatalConfig(err)
	}

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Add -allow-custom-base-url to the command when using -base-url
2. Verify the base URLs use HTTPS unless they are explicit loopback hosts with -allow-insecure-loopback
3. If you did not intend custom routing, remove the -base-url flags entirely

Example fix

# before
cache-replay -base-url openai=https://staging.example.com ...

# after
cache-replay -base-url openai=https://staging.example.com -allow-custom-base-url ...

if len(baseURLs) > 0 {
	if !allowCustomBaseURL {
		return errors.New("refusing custom base URLs without explicit opt-in")
	}
	for _, u := range baseURLs {
		if !strings.HasPrefix(u, "https://") && !isLoopback(u) {
			return fmt.Errorf("non-HTTPS non-loopback base URL %q", u)
		}
	}
}

When it happens

Trigger: Any invocation that includes one or more -base-url flags without also passing -allow-custom-base-url. Common when pointing replay at a staging mirror or a local fake provider.

Common situations: Testing against an internal staging endpoint or a mock server; forgetting the confirmation flag after copying a staging command template.

Related errors

• cache-replay: -execute requires -accept-live-cost, -output,
• want provider=https://host
• cache-replay: -trace and positive request/token/trace/respon
• cache-replay: verifier command must be an existing regular f
• invalid agent evidence identity

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