JuliusBrussee/caveman · error
azure request missing api-version
Error message
azure request missing api-version
What it means
On the legacy deployment chat-completions route, an api-version query parameter is mandatory. The adapter requires exactly one api-version and rejects requests that omit it before resolving the upstream URL.
Solutions
- Add ?api-version=<allowed-version> to the legacy deployment URL, e.g. api-version=2024-10-21.
- Configure the client/SDK to always append api-version for Azure deployment-style endpoints.
- Alternatively switch to the Foundry v1 route, where api-version is not required.
Example fix
// before GET /azure/openai/deployments/gpt-4o/chat/completions // after GET /azure/openai/deployments/gpt-4o/chat/completions?api-version=2024-10-21
Defensive patterns
Strategy: validation
Validate before calling
func legacyRouteHasVersion(rawURL string) bool {
u, err := url.Parse(rawURL)
if err != nil {
return false
}
p := strings.TrimPrefix(u.Path, "/azure")
parts := strings.Split(strings.Trim(p, "/"), "/")
isLegacy := len(parts) == 5 && parts[1] == "deployments" && parts[3] == "chat" && parts[4] == "completions"
return !isLegacy || len(u.Query()["api-version"]) == 1
} Prevention
- Always include api-version on deployment-style Azure OpenAI URLs.
- Configure the SDK's Azure client with an explicit APIVersion field rather than relying on defaults.
- Prefer the Foundry v1 route when you do not want to manage date-style versions.
When it happens
Trigger: A request to /azure/openai/deployments/{deployment}/chat/completions with no api-version query parameter at all.
Common situations: Switching a client from the Foundry v1 route (where api-version is optional) to the legacy deployment route without adding the parameter; SDKs that omit api-version expecting the proxy to inject it; hand-written curl commands.
Understand the failure class
Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.
Related errors
- azure Foundry api-version
- azure api-version is not on the allowlist
- azure legacy inference path
- azure request has duplicate api-version values
- Duplicate or reserved caveman_retrieve tool name
AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20).
Data as JSON: /api/errors/fb7efcd57f210703.
Report an issue: GitHub.
Appendix: source
Thrown at proxy/providers/azureopenai/azure_routing.go:61
}
if len(versions) == 1 && versions[0] != "v1" && versions[0] != "preview" {
return fmt.Errorf("azure Foundry api-version %q is not supported", versions[0])
}
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 {View on GitHub (pinned to 3ee70a1026)