cache-replay: verifier command must be an existing regular f

Error message

cache-replay: verifier command must be an existing regular file

What it means

Fatal config error from cache-replay: os.Stat on the -verifier-command path failed, or the path exists but is not a regular file (directory, symlink to nothing is covered by Stat failing, device, socket, etc.). The tool refuses to execute anything it cannot confirm as an on-disk regular file, which also rules out PATH lookup and shell builtins.

Source

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

	}
	target := cachebench.Target{RequestHitRate: *targetRate, TokenHitRate: *targetRate, MinEligibleRequest: *minEligible}
	if err := cachebench.ValidateReplayTarget(records, target); err != nil {
		fatalConfig(err)
	}
	if !*executeReplay {
		writeStdout(map[string]any{
			"schema": "caveman.cachebench.replay-preflight.v1", "execute": false,
			"trace_sha256": traceSHA, "preflight": preflight, "target": target,
			"message": "preflight only; no provider request sent",
		})
		return
	}
	if !*acceptCost || *outputPath == "" || !filepath.IsAbs(*outputPath) || *verifierPath == "" || !filepath.IsAbs(*verifierPath) {
		fatalConfig(errors.New("cache-replay: -execute requires -accept-live-cost, -output, and -verifier-command"))
	}
	verifierInfo, err := os.Stat(*verifierPath)
	if err != nil || !verifierInfo.Mode().IsRegular() {
		fatalConfig(errors.New("cache-replay: verifier command must be an existing regular file"))
	}
	if err := validateProviderCredentials(records); err != nil {
		fatalConfig(err)
	}
	environment, err := verifierEnvironment(verifierEnv)
	if err != nil {
		fatalConfig(err)
	}
	transport, err := cachebench.NewHTTPReplayTransport(cachebench.HTTPReplayConfig{
		Credentials: cachebench.HTTPReplayCredentials{
			OpenAIAPIKey: os.Getenv("OPENAI_API_KEY"), AnthropicAPIKey: os.Getenv("ANTHROPIC_API_KEY"),
			GeminiAPIKey: os.Getenv("GEMINI_API_KEY"), BedrockAPIKey: os.Getenv("AWS_BEARER_TOKEN_BEDROCK"),
			AWS: awssig.Credentials{AccessKeyID: os.Getenv("AWS_ACCESS_KEY_ID"), SecretAccessKey: os.Getenv("AWS_SECRET_ACCESS_KEY"), SessionToken: os.Getenv("AWS_SESSION_TOKEN")},
		},
		BaseURLs: map[string]string(baseURLs), AllowInsecureLoopback: *allowInsecureLoopback,
		MaxResponseBytes: *maxResponseBytes, RequestTimeout: *providerTimeout,
	})
	if err != nil {

View on GitHub (pinned to 27d5a3981a)

Solutions

Point -verifier-command at the real executable's absolute path, resolved with realpath or readlink -f
If the verifier needs arguments, pass them via repeatable -verifier-arg flags rather than embedding them in the path
Wrap interpreter-based verifiers in a shell script file so the path is a regular executable file

Example fix

# before
cache-replay -verifier-command jq ...

# after
# create /abs/run-verify.sh containing the invocation, then:
chmod +x /abs/run-verify.sh
cache-replay -verifier-command /abs/run-verify.sh -verifier-arg --arg -verifier-arg value ...

Defensive patterns

Strategy: validation

Validate before calling

resolved, err := filepath.EvalSymlinks(verifierPath)
if err != nil {
	return fmt.Errorf("verifier path unresolvable: %w", err)
}
info, err := os.Stat(resolved)
if err != nil || !info.Mode().IsRegular() {
	return fmt.Errorf("verifier %s is not a regular file", verifierPath)
}

Prevention

Store verifiers at fixed absolute paths inside the repo/image and reference that constant
Pass dynamic arguments via -verifier-arg, never by embedding them in -verifier-command

When it happens

Trigger: Passing a verifier name that relies on PATH resolution (e.g. -verifier-command jq); passing a directory; a dangling symlink; a typo in the absolute path.

Common situations: Assuming the flag behaves like a shell command line; moving the verifier script and forgetting to update the flag; symlinked toolchains where the link target is missing.

Related errors

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