JuliusBrussee/caveman · error

compat upstream

Error message

compat upstream %q: %w

What it means

A compat upstream entry has a name that failed openaicompat.ValidateName, and validateCompat wraps that failure with this prefix. Names are keys of the compat map and must conform to the validator's rules (e.g. allowed characters/format) since they identify the upstream in routing and config.

Solutions

1. Rename the compat upstream key to satisfy openaicompat.ValidateName (check its rules for allowed characters/format).
2. Use a simple lowercase alphanumeric/hyphen name (e.g. "my-openai") and retry Load.
3. Read the wrapped %w error in the message to see the exact rule violated.

Example fix

// before
[compat."My OpenAI!"]
base_url = "https://api.example.com/v1"
// after
[compat."my-openai"]
base_url = "https://api.example.com/v1"

if err := openaicompat.ValidateName(name); err != nil {
    return fmt.Errorf("compat upstream %q: %w", name, err)
}

When it happens

Trigger: Defining a compat upstream in config with a key that openaicompat.ValidateName rejects (bad characters, invalid format, wrong casing/length per that validator) and calling Load.

Common situations: Renaming upstreams with spaces or slashes in the key; uppercase or special-character keys copied from vendor docs; YAML/JSON keys accidentally including quotes or trailing whitespace.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• cave_breaker_retry_backoff_invalid
• cave_breaker_retry_requires_budget
• cave_breaker_retry_spend_invalid
• cave_breaker_threshold_invalid
• cave_budget_denomination_ambiguous

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/9a0f5abd60ad2431. Report an issue: GitHub.

Appendix: source

Thrown at proxy/internal/config/config.go:455

		}
	}
	return DefaultBedrockRegion
}

// BedrockBaseURL returns an explicit operator override or derives AWS's standard
// Runtime endpoint from BedrockRegion. Callers never need to paste a raw URL for
// the normal first-party path.
func (c Config) BedrockBaseURL() string {
	if configured := c.BaseURL("bedrock", ""); configured != "" {
		return configured
	}
	return fmt.Sprintf("https://bedrock-runtime.%s.amazonaws.com", c.BedrockRegion())
}

func (c Config) validateCompat() error {
	for name, upstream := range c.Compat {
		if err := openaicompat.ValidateName(name); err != nil {
			return fmt.Errorf("compat upstream %q: %w", name, err)
		}
		if strings.TrimSpace(upstream.BaseURL) == "" {
			return fmt.Errorf("compat upstream %q: base_url is required", name)
		}
		if err := openaicompat.ValidateBaseURL(upstream.BaseURL); err != nil {
			return fmt.Errorf("compat upstream %q: base_url: %w", name, err)
		}
		if err := openaicompat.ValidateForwardHeaders(upstream.ForwardHeaders); err != nil {
			return fmt.Errorf("compat upstream %q: forward_headers: %w", name, err)
		}
		if err := openaicompat.ValidateWireDialect(upstream.WireDialect); err != nil {
			return fmt.Errorf("compat upstream %q: %w", name, err)
		}
	}
	return nil
}

// providerEnvKey maps a provider name to the BYOK environment variable that

View on GitHub (pinned to 3ee70a1026)