JuliusBrussee/caveman · critical

cache-replay: OPENAI_API_KEY unavailable

Error message

cache-replay: OPENAI_API_KEY unavailable

What it means

Returned by validateProviderCredentials when the trace contains openai requests but the OPENAI_API_KEY environment variable is empty in the cache-replay process. Credential presence is checked per distinct provider found in the trace before any live request is made, so replay against OpenAI fails fast instead of 401-ing mid-run.

Source

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

	if err != nil {
		return nil, "", err
	}
	if limited.N <= 0 {
		return nil, "", fmt.Errorf("cache-replay: trace exceeds %d bytes", maxBytes)
	}
	return records, hex.EncodeToString(hash.Sum(nil)), nil
}

func validateProviderCredentials(records []cachebench.TraceRecord) error {
	providers := map[string]bool{}
	for _, record := range records {
		providers[record.Provider] = true
	}
	for provider := range providers {
		switch provider {
		case "openai":
			if os.Getenv("OPENAI_API_KEY") == "" {
				return errors.New("cache-replay: OPENAI_API_KEY unavailable")
			}
		case "anthropic":
			if os.Getenv("ANTHROPIC_API_KEY") == "" {
				return errors.New("cache-replay: ANTHROPIC_API_KEY unavailable")
			}
		case "gemini":
			if os.Getenv("GEMINI_API_KEY") == "" {
				return errors.New("cache-replay: GEMINI_API_KEY unavailable")
			}
		case "bedrock":
			if os.Getenv("AWS_BEARER_TOKEN_BEDROCK") == "" && (os.Getenv("AWS_ACCESS_KEY_ID") == "" || os.Getenv("AWS_SECRET_ACCESS_KEY") == "") {
				return errors.New("cache-replay: Bedrock bearer token or AWS access credentials unavailable")
			}
		default:
			return fmt.Errorf("cache-replay: unsupported provider %q", provider)
		}
	}
	return nil

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Export OPENAI_API_KEY in the environment of the cache-replay process (export OPENAI_API_KEY=... or env-file mechanism)
2. Confirm the trace actually needs OpenAI: if not, filter the trace to the providers you have keys for
3. In CI, add the secret under the exact name OPENAI_API_KEY

Example fix

# before
cache-replay -execute ...

# after
export OPENAI_API_KEY="$OPENAI_KEY_FROM_SECRET_MANAGER"
cache-replay -execute ...

providers := map[string]bool{}
for _, r := range records {
	providers[r.Provider] = true
}
if providers["openai"] && os.Getenv("OPENAI_API_KEY") == "" {
	return errors.New("set OPENAI_API_KEY before live replay")
}

When it happens

Trigger: Running cache-replay -execute on a trace with provider "openai" records without exporting OPENAI_API_KEY. The key must exist in the tool's own environment; note that verifier subprocesses get a scrubbed env and never see provider keys.

Common situations: CI job secrets not mapped to the env var name; exporting the key in a different shell than the one running the tool; .env file loaded by a wrapper but not by the direct invocation; trace recorded across multiple providers but only some keys provisioned.

Related errors

• cache-replay: ANTHROPIC_API_KEY unavailable
• cache-replay: GEMINI_API_KEY unavailable
• cache-replay: Bedrock bearer token or AWS access credentials
• no provider credential detected; pass --provider
• multiple provider credentials detected; pass --provider

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