JuliusBrussee/caveman · error

compat upstream name %q must match [a-z0-9][a-z0-9._-]{0,63}

Error message

compat upstream name %q must match [a-z0-9][a-z0-9._-]{0,63}

What it means

ValidateName enforces the compat upstream naming rule: names must match [a-z0-9][a-z0-9._-]{0,63}. Names with uppercase, spaces, leading separators, or excessive length fail this regex guard before reservation checks.

Source

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

	}
	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":
		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

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Rename the upstream using lowercase letters, digits, and . _ - only, starting with a letter or digit, max 64 chars
2. Check for uppercase or spaces introduced by tooling

When it happens

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