JuliusBrussee/caveman · error

compat upstream %q: %w

Error message

compat upstream %q: %w

What it means

Config.validateCompat wraps openaicompat.ValidateName for each entry in the compat map. A compat upstream name must match [a-z0-9][a-z0-9._-]{0,63} and must not be the reserved names 'stub' or 'openai-compatible', because the name becomes a route prefix mounted under /compat/. The wrapped error identifies which entry failed.

Source

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

		}
	}
	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)
		}
	}
	return nil
}

// providerEnvKey maps a provider name to the BYOK environment variable that
// holds its API key.
var providerEnvKey = map[string]string{
	"anthropic":         "ANTHROPIC_API_KEY",
	"openai":            "OPENAI_API_KEY",
	"gemini":            "GEMINI_API_KEY",
	"azure_openai":      "AZURE_OPENAI_API_KEY",

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Rename the compat key to a lowercase slug: 'openrouter', 'together-ai', 'deepseek.v3'
2. Keep it under 64 characters, starting with a letter or digit, using only [a-z0-9._-]
3. Avoid the reserved names 'stub' and 'openai-compatible'

Example fix

# before
compat:
  "OpenRouter":        # Error[1062]: invalid name
    base_url: https://openrouter.ai/api/v1

# after
compat:
  openrouter:
    base_url: https://openrouter.ai/api/v1

var compatNameRe = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{0,63}$`)

func validCompatName(name string) bool {
    if !compatNameRe.MatchString(name) {
        return false
    }
    return name != "stub" && name != "openai-compatible"
}

for name := range cfg.Compat {
    if !validCompatName(name) { /* reject before Load() */ }
}

When it happens

Trigger: compat: map key 'My Provider' (uppercase/space), 'grok/usa' (slash), '-leading' (starts with '-'), a name longer than 64 chars, or the reserved keys 'stub' or 'openai-compatible'.

Common situations: Pasting a vendor display name instead of a slug; using uppercase vendor names ('OpenRouter'); name collision with the built-in generic openai-compatible route.

Related errors

• compat upstream %q: base_url is required
• compat upstream %q: base_url: %w
• cave_budget_denomination_ambiguous
• cave_budget_max_invalid
• cave_budget_output_floor_invalid

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