Troubleshoot the Azure API Management CLI

Use this page to resolve common hiddenlayer-apim setup and deployment issues.

Azure Authentication Fails

Run:

az login
az account show

If the active subscription is wrong, set it explicitly:

az account set --subscription "<subscription-id>"

You can also set AZURE_SUBSCRIPTION_ID in .env.

APIM Resource Is Not Found

Check these settings:

RG=your-resource-group
APIM_NAME=your-apim-instance
AZURE_SUBSCRIPTION_ID=your-subscription-id

If the APIM service exists but the CLI still cannot see it, the signed-in identity is missing APIM permissions on that scope. See Azure permissions for the role and action requirements.

Azure Returns 401, 403, or `AuthorizationFailed`

AuthorizationFailed, 403 Forbidden, or 401 from any Microsoft.ApiManagement call means the signed-in identity is missing one of the required APIM actions. Confirm the signed-in identity:

az account show --query '{user:user.name, subscription:name, tenantId:tenantId}' -o table

List the APIM role assignments visible at the target scope:

az role assignment list \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-name>" \
  --include-inherited \
  --query '[].{role:roleDefinitionName, principal:principalName, scope:scope}' \
  -o table

If no role grants the actions in Azure permissions, assign API Management Service Contributor to the identity at the APIM service, resource group, or subscription scope, or add the missing actions to your custom role.

Deploy Stops Because a Resource Already Exists

hiddenlayer-apim deploy is non-destructive by default. It creates missing HiddenLayer resources and leaves matching resources unchanged. If an existing non-secret named value or policy fragment has different content, the command stops instead of overwriting it. Review the existing APIM resource. If you intentionally want the CLI to replace HiddenLayer-managed named values or fragments, run:

hiddenlayer-apim deploy --overwrite

When --overwrite would change something, the CLI lists the affected named values and policy fragments and prompts for yes before continuing. Secret named values are listed by name only; their values are not displayed. Existing secret named values are skipped unless --overwrite is used because Azure does not return secret values for comparison.

Apply Reports `apply cancelled`

hiddenlayer-apim apply previews the inbound and outbound fragments it will inject and waits for yes before updating the APIM policy. Any other input, an empty line, or no available stdin cancels the run. Type yes to confirm, or pass --yes to skip the prompt in non-interactive environments such as CI:

hiddenlayer-apim apply <api-id> --yes

Remove Reports `remove cancelled`

hiddenlayer-apim remove previews the fragment IDs it will delete and waits for yes. Any other input, an empty line, or no available stdin cancels the run. Type yes to confirm, or pass --yes to skip the prompt:

hiddenlayer-apim remove <api-id> --package v2-request-evals --yes
hiddenlayer-apim remove <api-id> --all --yes

Remove Does Not Detect Any Fragments

hiddenlayer-apim remove only removes HiddenLayer fragments that match the selected package (or every detected HiddenLayer fragment with --all). It reports No removable HiddenLayer fragments found in policy when:

The API policy has no HiddenLayer <include-fragment> references.
You selected a --package/--packages whose fragments are not present in the API policy. In that case, list what is actually applied and re-select the correct package:

hiddenlayer-apim status <api-id>
hiddenlayer-apim remove <api-id> --all

--all cannot be combined with --package or --packages. Use one or the other.

Apply Reports Missing Fragments

Run deploy first:

hiddenlayer-apim deploy --package v2-request-evals
hiddenlayer-apim apply <api-id> --package v2-request-evals

If you use multiple packages, deploy and apply the same package list.

Wrong Package Is Selected

Set the package explicitly:

hiddenlayer-apim deploy --package v2-request-evals
hiddenlayer-apim apply <api-id> --package v2-request-evals

Or set a default in .env:

HL_PACKAGE=v2-request-evals

Use --packages when you want request and response evaluation together:

hiddenlayer-apim apply <api-id> --packages v2-request-evals,v2-response-evals

HiddenLayer API Calls Use the Wrong Region

Set HL_HOST for your HiddenLayer environment:

# US
HL_HOST=hiddenlayer.ai

# EU
HL_HOST=eu.hiddenlayer.ai

Then redeploy with --overwrite if the APIM named value already exists:

hiddenlayer-apim deploy --overwrite

Runtime Action Header Is Missing

HL-Runtime-Action is set to BLOCK only when HiddenLayer blocks a request or response. For allow, detect, or redact outcomes, the header can be empty. Use curl -i or equivalent tooling to inspect response headers:

curl -i "https://<apim-name>.azure-api.net/<api-path>/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hello"}]}'

Response Evaluation Does Not Run

The response evaluation package skips:

model discovery requests such as GET /v1/models
streaming requests
non-JSON responses
empty responses

Disable streaming for requests you want APIM to evaluate on the outbound path.

​Azure Authentication Fails

​APIM Resource Is Not Found

​Azure Returns 401, 403, or AuthorizationFailed

​Deploy Stops Because a Resource Already Exists

​Apply Reports apply cancelled

​Remove Reports remove cancelled

​Remove Does Not Detect Any Fragments

​Apply Reports Missing Fragments

​Wrong Package Is Selected

​HiddenLayer API Calls Use the Wrong Region

​Runtime Action Header Is Missing

​Response Evaluation Does Not Run