JuliusBrussee/caveman · error

compat upstream name %q is reserved

Error message

compat upstream name %q is reserved

What it means

ValidateName reserves the names "stub" and "openai-compatible" because they collide with built-in route identifiers. Configuring a compat upstream under one of these names is rejected even though the name itself is well-formed.

Source

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

	}
	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":
		return fmt.Errorf("compat upstream name %q is reserved", name)
	default:
		return nil
	}
}

func ValidateBaseURL(raw string) error {
	_, err := parseBaseURL(raw, "compat")
	return err
}

// ResolveUpstreamURL intentionally ignores RouteContext.BaseURL. Named mounts
// are configured as independent static upstreams (`compat:` in standalone or
// CAVE_COMPAT_UPSTREAMS in managed mode); applying the generic project
// openai_compatible override here would collapse every named route onto one
// target. The default /compat/ adapter is the route that honors BaseURL.
func (a namedAdapter) ResolveUpstreamURL(_ context.Context, req *http.Request, _ providers.RouteContext) (*url.URL, error) {
	if req == nil || req.URL == nil {
		return nil, fmt.Errorf("compat request URL is missing")

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Choose a different upstream name that is not stub or openai-compatible
2. Update the config that defines the compat upstream

When it happens

Trigger: Thrown at proxy/providers/openaicompat/openaicompat.go:208 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/487c21ca5b20b72f. Report an issue: GitHub.