AuthorizationFailed names the three facts you need: the caller's object ID, the action, and the scope. Everything below is a variation on "that object has no role granting that action at that scope", plus the cases where it does but the change hasn't applied yet.

Check for every row: who is calling (az account show --query user, or the object ID in the message), then az role assignment list --assignee <object-id> --all --include-inherited --include-groups -o table.

Using a resource

Message	Cause → fix	Check
`The client '<name>' with object id '<id>' does not have authorization to perform action '<action>' over scope '<scope>' or the scope is invalid. If access was recently granted, please refresh your credentials.` (`AuthorizationFailed`)	No role grants `<action>` at `<scope>` or above, for this identity. Assign a role that includes the action at that scope. Also returned when the resource provider isn't registered (`az provider register --namespace <ns>`)	The listing above; `az provider show --namespace <ns> --query registrationState`
Same, but you assigned the role minutes ago	Up to ~10 minutes to apply; ARM caches. Sign out and in, or get a new token	`az role assignment list` shows it; retry later
Same, for a guest user	The guest needs its own assignment in this tenant	The listing, run against the guest's object ID
`LinkedAuthorizationFailed`	The deployment touches a resource in a tenant (or scope) the caller can't act on: often a linked resource in another tenant or subscription	Compare `az account show --query tenantId` with the linked resource's tenant
Storage data action + ABAC condition with a GUID comparison operator	That combination isn't supported. Remove the Storage data actions from the custom role, or rewrite the condition without GUID operators	The assignment's `condition`

Creating role assignments

Message	Cause → fix	Check
`Failed to add <principal> as <role> for <scope> : The client … does not have authorization or an ABAC condition not fulfilled to perform action 'Microsoft.Authorization/roleAssignments/write' …`	The caller can't assign roles here (Contributor can't), or a delegation condition restricts which roles or principals it may assign	The caller's assignments; look for a `condition` on its Role Based Access Control Administrator assignment
`Insufficient privileges to complete the operation` (from `az role assignment create`)	The CLI looked the assignee up in Microsoft Graph and the caller (a service principal) can't read the directory. Use `--assignee-object-id` with `--assignee-principal-type`	Re-run with those flags
`PrincipalNotFound` `Principal <id> does not exist in the directory <tenant>. … replication delay …`	The principal was just created and hasn't replicated, or the ID is wrong (a client ID instead of the object ID). Set `principalType`; for new groups, wait a few minutes	`az ad sp show --id <id>` (object ID vs `appId`)
`Tenant ID, application ID, principal ID, and scope are not allowed to be updated. (code: RoleAssignmentUpdateNotPermitted)`	A deployment reused an assignment name for a different principal (identity deleted and recreated). Names are global GUIDs and assignments are immutable: derive the name with `guid(scope, principalId, roleDefinitionId)`	The template's `name` expression
`The role assignment already exists.` (`RoleAssignmentExists`, 409)	Microsoft's FAQ: often intermittent or benign, retry. Field report (Q&A): the same principal, role and scope already existed under another name, created by hand. Use deterministic names; treat it as success in scripts	`az role assignment list --assignee <id> --role <role> --scope <scope>`
`No more role assignments can be created (code: RoleAssignmentLimitExceeded)`	The subscription's role-assignment limit is reached. Remove unused ones (including Identity not found entries) and assign to groups	`az role assignment list --all --query "length(@)"` vs the limit on the subscription limits page
Assignment shows Identity not found / Unknown	The principal was deleted without removing its assignment (or is still replicating, if just invited)	Empty `principalName` in `az role assignment list --scope <scope>`
`Cannot delete the last RBAC admin assignment`	Removing the last Owner at subscription scope isn't allowed by default	Subscription's Owner assignments

Custom roles

Message	Cause → fix	Check
`… has permission to perform action 'Microsoft.Authorization/roleDefinitions/write' on scope … however, it does not have permission … on the linked scope(s) …`	You lack `roleDefinitions/write` on one of the role's `AssignableScopes`, or a scope is invalid	Each scope in `AssignableScopes`
`There are existing role assignments referencing role (code: RoleDefinitionHasAssignments)`	Remove the assignments that use it first	`az role assignment list --role <role-name> --all`
`You cannot add data action permissions when you have a management group as an assignable scope`	Custom roles with `DataActions` can't be assignable at management-group scope; use subscriptions	The role's `AssignableScopes`
Can't add a second management group to `AssignableScopes`	One management group at most	—
Can't update or delete a custom role	No `roleDefinitions/write`, or an assignable subscription is disabled	`az account show --subscription <id> --query state`

When none of these fits

If the role is right and current, the refusal comes from another layer: a deny assignment, Azure Policy (RequestDisallowedByPolicy), a service firewall, or a data-plane permission model (Key Vault access policies, storage shared-key settings). Work through guides/identity/fix-access-denied.md.