JuliusBrussee/caveman · critical

cache-replay: GEMINI_API_KEY unavailable

Error message

cache-replay: GEMINI_API_KEY unavailable

What it means

Returned by validateProviderCredentials when the trace contains gemini requests but GEMINI_API_KEY is empty in the cache-replay process. It is the Gemini branch of the per-provider pre-flight credential check run during -execute validation.

Source

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

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
}

func verifierEnvironment(extra []string) ([]string, error) {
	allowed := map[string]bool{"PATH": true, "LANG": true, "LC_ALL": true, "TMPDIR": true}
	blocked := map[string]bool{
		"OPENAI_API_KEY": true, "ANTHROPIC_API_KEY": true, "GEMINI_API_KEY": true,
		"AWS_BEARER_TOKEN_BEDROCK": true, "AWS_ACCESS_KEY_ID": true, "AWS_SECRET_ACCESS_KEY": true, "AWS_SESSION_TOKEN": true,
	}

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Export GEMINI_API_KEY for the cache-replay process
2. If your org uses GOOGLE_API_KEY, bridge it: export GEMINI_API_KEY="$GOOGLE_API_KEY"
3. Remove gemini records from the trace if Gemini replay is out of scope

Example fix

# before
cache-replay -execute ...

# after
export GEMINI_API_KEY="$GOOGLE_AI_STUDIO_KEY"
cache-replay -execute ...

if providers["gemini"] && os.Getenv("GEMINI_API_KEY") == "" {
	return errors.New("set GEMINI_API_KEY before live replay")
}

When it happens

Trigger: Trace with provider "gemini" records and no GEMINI_API_KEY in the tool's environment.

Common situations: Google AI key stored as GOOGLE_API_KEY in existing infra and not aliased; new provider added to a workload without updating secret provisioning; CI matrix jobs sharing a config where only some jobs get the Gemini secret.

Related errors

• cache-replay: OPENAI_API_KEY unavailable
• cache-replay: ANTHROPIC_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/57c11a45df4580cc. Report an issue: GitHub.