JuliusBrussee/caveman · error

compat upstream %q base_url: %w

Error message

compat upstream %q base_url: %w

What it means

Wrap in NewNamed: ValidateBaseURL rejected the upstream's base_url (scheme, host, userinfo, or path-shape failure). The named compat upstream's base_url configuration is at fault; the wrapped error carries the specifics.

Source

Thrown at proxy/providers/openaicompat/openaicompat.go:232

func inspectOpenAICompatible(ctx context.Context, base providers.Base, body providers.BodyReader, headers http.Header) (providers.RequestMetadata, error) {
	meta, err := base.InspectRequest(ctx, body, headers)
	if path := headers.Get("x-cave-route-path"); path != "" {
		meta.Endpoint = path
	}
	return meta, err
}

// NewNamed builds a dedicated OpenAI-compatible upstream mounted at
// /compat/<name>/. The provider enum intentionally stays openai_compatible so
// usage/cost telemetry keeps using the shared OpenAI-shape parser.
func NewNamed(name, baseURL string) (providers.Adapter, error) {
	if err := ValidateName(name); err != nil {
		return nil, err
	}
	baseURL = strings.TrimSpace(baseURL)
	if err := ValidateBaseURL(baseURL); err != nil {
		return nil, fmt.Errorf("compat upstream %q base_url: %w", name, err)
	}
	prefix := "/compat/" + name
	return namedAdapter{
		Base: providers.Base{
			Provider: "openai_compatible",
			BaseURL:  baseURL,
			Routes:   []string{prefix + "/"},
		},
		prefix: prefix,
	}, nil
}

func ValidateName(name string) error {
	if !validName.MatchString(name) {
		return fmt.Errorf("compat upstream name %q must match [a-z0-9][a-z0-9._-]{0,63}", name)
	}
	switch name {
	case "stub", "openai-compatible":

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Set an absolute http(s) base URL without userinfo, fragment, or encoded path tricks
2. Check the compat upstream config / CAVE_COMPAT_UPSTREAMS value for typos

When it happens

Trigger: Thrown at proxy/providers/openaicompat/openaicompat.go:189 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@5184b3d11a (2026-08-18). Data as JSON: /api/errors/88f8e3f3825319c0. Report an issue: GitHub.