Why a Correct-Looking Azure Role GUID Can Still Fail Your Marketplace Deployment

A wrong Azure role-definition GUID in your ARM or Bicep packaging will pass bicep lint, pass az bicep build, and pass a code review — and still fail a customer's deployment. None of those checks resolve the GUID against Azure; they only check syntax. The failure only shows up when a real customer runs the deployment and gets "role definition not found," sometimes taking down the entire managed-app install with it, not just the one role assignment.

This happened to us twice on the same product, in two different ways. Once, the GUID resolved to nothing — a typo one character deep into an otherwise-correct-looking string. The second time was worse: it resolved to a different, real role than the one intended, which doesn't even throw an error at deploy time. A reviewer had pattern-matched the first eight characters of the GUID, recognized them as "the Key Vault one," and approved it. Both times, the fix was cheap — the catch was the hard part.

How do you actually verify an Azure role-definition GUID?

Run this against the live source of truth, every time a roleDefinitionId changes — not just when it's first written:

az role definition list --name "Key Vault Secrets Officer" --query "[0].name" -o tsv

Compare the full GUID, not just the prefix. And after any republish, download the actual built package — not the source repo — and grep the compiled template for the GUIDs you expect to see present, and the ones you expect to be gone. "CI is green" only tells you the syntax was valid; it says nothing about whether the platform will actually recognize what you wrote.

What else trips up Azure Marketplace co-sell submissions?

This is one of several submission-time traps that don't show up until you've already hit them: a secret that only appears in the build, never the source, and can get your entire live listing pulled from distribution; Partner Center limits (keyword slots, character counts, category taxonomy) that are quietly different from what the docs and third-party evaluations say; a "Review failed" co-sell badge that, more often than not, means nothing's actually wrong — just a revenue threshold not yet crossed.