🚨 Azure Error: 'PrincipalNotFound: Principal does not exist in the directory' — Cause, Fix, and Troubleshooting Guide

What this error means

Azure returns PrincipalNotFound when you create a role assignment for an object id that Entra ID cannot resolve to a real principal in the tenant. The RBAC layer verifies the principal exists before writing the assignment, and if the directory does not know the id, the grant is rejected. The literal error:

{
  "error": {
    "code": "PrincipalNotFound",
    "message": "Principal aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee does not exist in the directory 11112222-3333-4444-5555-666677778888. Check that you have the correct principal ID. If you are creating this principal and then immediately assigning a role, this error might occur if the replication has not completed or you are using the wrong principal type for the API."
  }
}

The message even names the two usual causes: replication lag for a brand-new identity, or the wrong principalType/id.

What users report

• az role assignment create fails with PrincipalNotFound right after creating a managed identity or service principal.
• An ARM/Bicep deployment that creates an identity and grants it a role in the same template fails on the role assignment.
• The grant succeeds when re-run a minute later (classic replication lag), or never succeeds (wrong id).
• The object id used is actually an application (client) id rather than the service principal’s object id.

Tenant and app configuration causes

• Replication lag — the identity was just created and has not yet propagated across Entra ID when the assignment is attempted milliseconds later.
• Wrong id supplied — using the app registration’s application (client) id or a user-assigned identity’s client id instead of the object (principal) id.
• Wrong tenant — the principal exists in a different tenant than the one the assignment targets.
• Deleted principal — the service principal or identity was deleted (or its app registration removed), leaving a dangling id.
• Missing principalType — in ARM, omitting principalType makes RBAC do an extra directory lookup that fails during the propagation window.

Confirming tenant configuration

Confirm the object id actually resolves in the tenant. For a managed identity:

az identity show \
  --name my-uami --resource-group id-rg \
  --query "{principalId:principalId, clientId:clientId}" -o json

Use principalId (the object id) for the assignment, never clientId. For a service principal, resolve the object id from the app id:

az ad sp show --id <appId> --query id -o tsv

Verify the principal is visible directory-wide:

az ad sp show --id <objectId> --query "{name:displayName, id:id, appId:appId}" -o json
# or for a user
az ad user show --id <objectId> --query "{name:displayName, id:id}" -o json

If these return “not found,” the id is wrong, deleted, or in another tenant — check which:

az account show --query "{tenant:tenantId}" -o tsv

Resolution

Use the object id, not the client id. Grant against principalId:

az role assignment create \
  --assignee-object-id "$(az identity show -n my-uami -g id-rg --query principalId -o tsv)" \
  --assignee-principal-type ServicePrincipal \
  --role "Key Vault Secrets User" \
  --scope "/subscriptions/1111.../resourceGroups/app-rg/providers/Microsoft.KeyVault/vaults/app-kv"

Passing --assignee-principal-type ServicePrincipal skips the directory graph lookup that fails during propagation.

Handle replication lag in automation — retry with backoff:

for i in 1 2 3 4 5; do
  az role assignment create --assignee-object-id <objectId> \
    --assignee-principal-type ServicePrincipal --role Reader --scope <scope> && break
  sleep 20
done

In Bicep/ARM, always set principalType and let the implicit dependency (referencing the identity’s principalId) order the deployment:

properties: {
  principalId: uami.properties.principalId
  roleDefinitionId: roleDefinitionId
  principalType: 'ServicePrincipal'
}

If the principal was deleted, recreate it (or point at the correct existing one) and use its current object id.

Avoiding tenant drift

• az role assignment create --assignee does a graph lookup. During the propagation window that lookup can fail; prefer --assignee-object-id + --assignee-principal-type to skip it.
• Client id vs object id is the number-one mistake. A user-assigned identity exposes both; RBAC wants the object/principal id.
• Cross-tenant guests need to be present as a principal in the target tenant; a guest invitation that is still pending will not resolve.
• Same template, immediate grant almost always needs principalType set so the deployment does not race replication.

Related tenant errors

• RoleAssignmentExists — the flip side: a duplicate grant for a principal that does exist.
• AuthorizationFailed — the caller lacks permission to create the assignment at all.
• LinkedAuthorizationFailed — a linked-scope permission gap during deployment.