The @metadata decorators in main.bicep prevent deployment on free Azure subscriptions

[Prachig-Microsoft]

Problem

In the Customer Chatbot Solution Accelerator (https://github.com/microsoft/customer-chatbot-solution-accelerator/), the @metadata decorators in main.bicep blocks deployment via azd up for users with free Azure subscriptions.

@metadata({
azd:{
type: 'location'
usageName: [
'OpenAI.GlobalStandard.gpt4.1-mini,50'
'OpenAI.GlobalStandard.gpt-realtime-mini,1'
]
}
})

Error

ERROR: prompting for value: getting locations with quota: no location found with enough quota for
OpenAI.GlobalStandard.gpt4.1-mini ( Cap: 50 ) and OpenAI.GlobalStandard.gpt-realtime-mini ( Cap: 1 )

Actual Quota Available (Free Subscription)

[East] US 2 (AI Services)

OpenAI.GlobalStandard.gpt4.1-mini:
Available: 5000
Required: 50

OpenAI.GlobalStandard.gpt-realtime-mini:
Available: 20
Required: 1

OpenAI.GlobalStandard.text-embedding-ada-002:
Available: 1000
Required: 10

All quotas are well within limits for deployment, yet azd blocks it.

Workaround

Commenting out the @metadata block with usageName in main.bicep allows successful deployment:

SUCCESS: Your up workflow to provision and deploy to Azure completed in 4 minutes 44 seconds.

Suggested Fix

• Investigate why azd's quota pre-check reports insufficient quota on free subscriptions when capacity is actually available
• Document this limitation for free subscription users
• Consider making the usageName quota check a warning rather than a blocker in azd

Environment

• Subscription type: Azure Free (Pay-As-You-Go not enabled)
• Subscription ID: 6becd867-e9d1-4ed9-a7a7-5bf1260XXXXX
• Deployment method: azd up
• Regions used: Australia East (main resources), East US 2 (AI services)

Could you please help us understand the significance of the metadata decorator and blocker in free subscription deployment.

[Akhileswara-Microsoft]

facing same issue In the Content generation (https://github.com/microsoft/content-generation-solution-accelerator), the @metadata decorators in main.bicep blocks deployment via azd up for users with free Azure subscriptions.

@metadata({
azd: {
type: 'location'
usageName: [
'OpenAI.GlobalStandard.gpt-5.1,150'
'OpenAI.GlobalStandard.gpt-image-1-mini,1'
]
}
})

error:

Workaround

Commenting out the @metadata block with usageName in main.bicep allows successful deployment:

Environment

Subscription type: Azure Free (Pay-As-You-Go not enabled)
Subscription ID: f8d1be2a-c42b-4c8b-926b-65cc937bf50f
Deployment method: azd up
Regions used: Sweden central

Could you please help us understand the significance of the metadata decorator and blocker in free subscription deployment.

[vhvb1989]

Debug Notes & Root Cause Analysis

Reproduction

Reproduced on a fresh Azure Free subscription (Pay-As-You-Go not enabled) using azd up with --debug logging against the customer-chatbot-solution-accelerator.

What happens

azd performs a 2-step quota pre-check before prompting the user for a deployment location:

1. Step 1 – SKU discovery: azd calls GET /subscriptions/{subId}/providers/Microsoft.CognitiveServices/skus?api-version=2025-06-01. This returns 200 OK with a large (~221KB) response listing all available SKUs/models and their supported locations. From this, azd identifies candidate locations (e.g., eastus2, francecentral, swedencentral). ✅ This step works correctly.

2. Step 2 – Quota/usage check per location: For each candidate location, azd calls GET /subscriptions/{subId}/providers/Microsoft.CognitiveServices/locations/{location}/usages?api-version=2025-06-01. On free subscriptions, all these calls return 200 OK with Content-Length: 12 — which is just {"value":[]} (an empty array).

Root Cause

The bug is in cli/azd/pkg/ai/model_service.go — ListLocationsWithQuota().

The core logic (around line 253-266) iterates over the usages returned per location and checks if any usage entry matches the required UsageName with sufficient remaining capacity:

found := slices.ContainsFunc(usages, func(u *armcognitiveservices.Usage) bool {
    if u.Name == nil || u.Name.Value == nil || *u.Name.Value != req.UsageName {
        return false
    }
    remaining := safeFloat64(u.Limit) - safeFloat64(u.CurrentValue)
    return remaining >= minCap
})
if !found {
    return true // skip this location
}

When the /usages API returns an empty array ({"value":[]}), usages is an empty slice. slices.ContainsFunc on an empty slice always returns false, so found is always false, and every location is skipped — even though the models are actually available and the quota is sufficient.

The same pattern also affects ListModelLocationsWithQuota() (line ~277) and other callers of ListUsages() / listUsagesByLocation() in the same file.

Why free subscriptions return empty usages

The Azure Cognitive Services /usages API appears to not return usage entries for subscriptions that have not yet provisioned any Cognitive Services resources or that are on the free tier. This is likely an ARM API behavior difference — paid subscriptions return the full list of usage/quota entries even before any resources are created, while free subscriptions return an empty list.

---

Suggested Fix: Treat empty usages as full quota available

The fix should be in cli/azd/pkg/ai/model_service.go.

Approach

When the /usages API returns an empty array for a location, treat it as "0 current usage" rather than "no quota". The SKUs endpoint already confirmed the models are available in those locations, so empty usages should mean the subscription has not consumed any quota yet.

Specific changes needed

1. ListLocationsWithQuota() (~line 253)

Current logic skips a location when no matching usage entry is found. Change it so that when usages is empty (len 0), the location is not skipped — it should be treated as having full quota available.

sharedResults.Range(func(loc string, usages []*armcognitiveservices.Usage) bool {
    // If usages is empty (e.g., free subscriptions return no usage data),
    // assume full quota is available since the SKU endpoint already
    // confirmed the models are supported in this location.
    if len(usages) == 0 {
        results = append(results, loc)
        return true
    }

    for _, req := range requirements {
        minCap := req.MinCapacity
        if minCap <= 0 {
            minCap = 1
        }
        found := slices.ContainsFunc(usages, func(u *armcognitiveservices.Usage) bool {
            if u.Name == nil || u.Name.Value == nil || *u.Name.Value != req.UsageName {
                return false
            }
            remaining := safeFloat64(u.Limit) - safeFloat64(u.CurrentValue)
            return remaining >= minCap
        })
        if !found {
            return true // skip this location
        }
    }
    results = append(results, loc)
    return true
})

2. Audit other callers of ListUsages() / listUsagesByLocation()

The same empty-usages issue affects other functions in model_service.go that check remaining := usage.Limit - usage.CurrentValue. These also need the same defensive handling. Specifically check:

• ListModelLocationsWithQuota() (~line 277) — same pattern, iterates usages per location
• listUsagesByLocation() (~line 1038) — aggregates usages across locations
• The model resolution logic (~line 442, 480) in prompt_service.go that calls ListUsages()

For each, when usages is empty, the function should not reject the location/model.

3. Add a test case

Add a test in the corresponding _test.go file that mocks GetAiUsages returning an empty slice and verifies that ListLocationsWithQuota still includes that location in results (rather than filtering it out).

Why this approach is correct

• The SKUs endpoint already validates that the model is available in the location
• Empty usages logically means 0 current consumption, not 0 quota limit
• This is a general fix that handles any subscription type that returns empty usages (not just free tier)
• No need to detect or special-case subscription types

[Roopan-Microsoft]

Thanks @vhvb1989 for this fix. This helps template to get used by many end users.