{"record":{"id":"30e290c84036ff8b","repo":"JuliusBrussee/caveman","slug":"azure-api-version-q-is-not-on-the-allowlist","errorCode":null,"errorMessage":"azure api-version %q is not on the allowlist","messagePattern":"azure api-version %q is not on the allowlist","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"proxy/providers/azureopenai/azure_routing.go","lineNumber":64,"sourceCode":"\t\t}\n\t\treturn nil\n\t}\n\tif !legacyChatCompletionsRoute(u.Path) {\n\t\treturn fmt.Errorf(\"azure legacy inference path %q is not supported\", u.Path)\n\t}\n\tversions := u.Query()[\"api-version\"]\n\tif len(versions) > 1 {\n\t\treturn fmt.Errorf(\"azure request has duplicate api-version values\")\n\t}\n\tversion := \"\"\n\tif len(versions) == 1 {\n\t\tversion = versions[0]\n\t}\n\tif version == \"\" {\n\t\treturn fmt.Errorf(\"azure request missing api-version\")\n\t}\n\tif !apiVersionAllowed(version) {\n\t\treturn fmt.Errorf(\"azure api-version %q is not on the allowlist\", version)\n\t}\n\treturn nil\n}\n\nfunc foundryV1InferenceRoute(path string) bool {\n\tpath = strings.TrimPrefix(path, \"/azure\")\n\tswitch path {\n\tcase \"/openai/v1/chat/completions\", \"/openai/v1/responses\":\n\t\treturn true\n\tdefault:\n\t\treturn false\n\t}\n}\n\nfunc legacyChatCompletionsRoute(path string) bool {\n\tpath = strings.TrimPrefix(path, \"/azure\")\n\tparts := strings.Split(strings.Trim(path, \"/\"), \"/\")\n\tif len(parts) != 5 || parts[0] != \"openai\" || parts[1] != \"deployments\" ||","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/proxy/providers/azureopenai/azure_routing.go#L46-L82","documentation":"On the legacy deployment route the api-version value must appear in the allowlist (built-in list of dated versions plus preview/latest, overridable via CAVE_AZURE_API_VERSION_ALLOWLIST). The request carried an api-version that is not on that list, so the adapter refuses it to prevent unverified or deprecated versions.","triggerScenarios":"A request to /azure/openai/deployments/{deployment}/chat/completions?api-version=X where X is not in the effective allowlist — e.g. api-version=2023-05-15, or a value removed when the operator set a custom CAVE_AZURE_API_VERSION_ALLOWLIST.","commonSituations":"Azure retiring/renaming api-versions; an operator narrowing CAVE_AZURE_API_VERSION_ALLOWLIST without updating all clients; older SDKs pinned to retired versions; typos in the env var (spaces, wrong separator).","solutions":["Use an allowlisted api-version such as 2024-10-21, 2025-04-01-preview, or latest.","If the version is required, set CAVE_AZURE_API_VERSION_ALLOWLIST (comma-separated) to include it.","Upgrade the client SDK so it emits a current Azure OpenAI api-version.","Check the CAVE_AZURE_API_VERSION_ALLOWLIST value for typos, stray spaces, or missing entries."],"exampleFix":"// before\nexport CAVE_AZURE_API_VERSION_ALLOWLIST=2025-04-01-preview\nGET /azure/openai/deployments/gpt-4o/chat/completions?api-version=2024-06-01\n// after\nexport CAVE_AZURE_API_VERSION_ALLOWLIST=2024-06-01,2025-04-01-preview\nGET /azure/openai/deployments/gpt-4o/chat/completions?api-version=2024-06-01","handlingStrategy":"validation","validationCode":"// Go: check against the same allowlist the adapter uses before sending\nfunc apiVersionAllowed(version string, allowlist []string) bool {\n\tfor _, v := range allowlist {\n\t\tif v == version {\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep client SDK api-version and CAVE_AZURE_API_VERSION_ALLOWLIST in sync when you customize the allowlist.","Upgrade SDKs proactively as Azure retires dated api-versions.","Pin one allowlisted version (e.g. 2025-04-01-preview) in client configuration.","When narrowing the allowlist, grep clients/configs for versions that would be dropped."],"tags":["azure","openai","api-version","allowlist","config"],"backgroundTag":"unsupported-enum-value","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}