JuliusBrussee/caveman · error

azure api-version %q is not on the allowlist

Error message

azure api-version %q is not on the allowlist

What it means

Legacy-route api-version values are checked against an allowlist: built-in dates 2024-02-01, 2024-06-01, 2024-08-01-preview, 2024-10-21, 2025-01-01-preview, 2025-03-01-preview, 2025-04-01-preview, 'preview', 'latest' — overridable via the comma-separated CAVE_AZURE_API_VERSION_ALLOWLIST env var. Pinning versions prevents clients from selecting unverified or deprecated Azure API behavior through the proxy.

Source

Thrown at proxy/providers/azureopenai/azure_routing.go:64

		}
		return nil
	}
	if !legacyChatCompletionsRoute(u.Path) {
		return fmt.Errorf("azure legacy inference path %q is not supported", u.Path)
	}
	versions := u.Query()["api-version"]
	if len(versions) > 1 {
		return fmt.Errorf("azure request has duplicate api-version values")
	}
	version := ""
	if len(versions) == 1 {
		version = versions[0]
	}
	if version == "" {
		return fmt.Errorf("azure request missing api-version")
	}
	if !apiVersionAllowed(version) {
		return fmt.Errorf("azure api-version %q is not on the allowlist", version)
	}
	return nil
}

func foundryV1InferenceRoute(path string) bool {
	path = strings.TrimPrefix(path, "/azure")
	switch path {
	case "/openai/v1/chat/completions", "/openai/v1/responses":
		return true
	default:
		return false
	}
}

func legacyChatCompletionsRoute(path string) bool {
	path = strings.TrimPrefix(path, "/azure")
	parts := strings.Split(strings.Trim(path, "/"), "/")
	if len(parts) != 5 || parts[0] != "openai" || parts[1] != "deployments" ||

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Switch the client to a version in the built-in list (e.g. 2024-10-21 or 2025-04-01-preview).
2. If the version is verified in your environment, extend the allowlist: CAVE_AZURE_API_VERSION_ALLOWLIST=2024-10-21,2023-05-15.
3. Check the env var for typos — note it REPLACES the default list entirely, so include every version you need.

Example fix

# before
export CAVE_AZURE_API_VERSION_ALLOWLIST=2024-10-21
curl "...?api-version=2025-04-01-preview"   # rejected

# after
export CAVE_AZURE_API_VERSION_ALLOWLIST=2024-10-21,2025-04-01-preview
curl "...?api-version=2025-04-01-preview"

allowed := map[string]bool{}
for _, v := range strings.Split(os.Getenv("CAVE_AZURE_API_VERSION_ALLOWLIST"), ",") {
    if v = strings.TrimSpace(v); v != "" {
        allowed[v] = true
    }
}
version := u.Query().Get("api-version")
if !allowed[version] {
    return fmt.Errorf("api-version %q not allowlisted; add it to CAVE_AZURE_API_VERSION_ALLOWLIST or use a listed version", version)
}

func apiVersionAllowed(version string) bool {
    for _, v := range allowlist() { // env override or built-in defaults
        if v == version {
            return true
        }
    }
    return false
}

if err := validateAzureRequest(req.URL); err != nil {
    if strings.Contains(err.Error(), "not on the allowlist") {
        http.Error(w, "api-version rejected; pin a listed version or extend CAVE_AZURE_API_VERSION_ALLOWLIST", http.StatusBadRequest)
        return
    }
    http.Error(w, err.Error(), http.StatusBadRequest)
}

When it happens

Trigger: Sending ?api-version=2023-05-15 (older than the floor) or a brand-new date the build predates; setting CAVE_AZURE_API_VERSION_ALLOWLIST to a narrower list that no longer contains the version your SDK sends.

Common situations: An older SDK pinned to a pre-2024 version; a newly released Azure version not yet added to the built-in list; an operator tightened the env allowlist and forgot a client still on the old value.

Related errors

• azure bearer credentials are unsupported; use an API key
• azure Foundry api-version %q is not supported
• cachebench: no providers
• cachebench: provider population exceeds 1024
• cachebench: invalid observation read limits

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