AZURE
AADUserNotFound - AAD User Not Found: User Does Not Exist
Seeing AADUserNotFound tells you Azure AD (Entra ID) couldn't locate the user—UPN format is wrong (must be user@domain), user was deleted, or they're in another tenant you can't access. This 404 client-side error happens when Azure AD validates user identifiers before operations. Most common in RBAC role assignments for VM access, but also surfaces in AKS cluster RBAC, Azure SQL database user management, and App Service deployment permissions. Cross-tenant access requires B2B federation or guest user invitations. Soft-deleted users may be recoverable within the 30-day retention window.
#Common Causes
- →Invalid UPN Format: The user principal name structure is incorrect or contains typos. UPNs must follow the format user@domain (e.g., john.doe@contoso.com). Common mistakes include missing @ symbol, wrong domain, or typos. This is persistent—you must use the correct UPN.
- →Deleted User: The user has been soft-deleted or permanently deleted from Azure AD. Deleted users aren't accessible via standard queries. Soft-deleted users may be recoverable within the retention period (typically 30 days). This is persistent—you must use a different user or restore the deleted user if possible.
- →Cross-Tenant Access: The user exists in a different tenant, and you don't have access. Cross-tenant access requires B2B federation configuration or guest user invitation. Simply knowing the UPN doesn't grant access. This is persistent—you must get access or use a user in your tenant.
✓Solutions
- 1Step 1: Diagnose - List all users to see valid UPNs: az ad user list --query "[].{DisplayName:displayName,UserPrincipalName:userPrincipalName,ObjectId:id}" --output table
- 2Step 2: Diagnose - Search for user by display name: az ad user list --filter "displayName eq '<name>'" --query "[].{DisplayName:displayName,UserPrincipalName:userPrincipalName}" --output table
- 3Step 3: Diagnose - Search for user by email address: az ad user list --filter "mail eq '<email>' or otherMails/any(x:x eq '<email>')" --output table
- 4Step 4: Fix - If UPN format is wrong, use the correct format from the user list. Verify the domain matches your tenant.
- 5Step 5: Fix - If user was deleted, check if soft-deleted and restore within retention period. Use Azure Portal > Azure AD > Users > Deleted users to restore.
- 6Step 6: Fix - For cross-tenant access, ensure B2B federation is configured or request guest user invitation from the target tenant administrator.
- 7Step 7: Verify - After finding the correct user or restoring, retry your operation. It should succeed instead of returning AADUserNotFound.
</>Code Examples
Azure AD User Lookup and Verification
1# This script helps diagnose AADUserNotFound by searching for users
2
3# Step 1: Example user principal name to search (replace with your UPN)
4UPN="user@yourdomain.onmicrosoft.com"
5echo "Searching for user: ${UPN}"
6
7# Step 2: Try to show user by UPN
8echo "Attempting to find user by UPN..."
9if az ad user show \
10 --id ${UPN} \
11 --query "{DisplayName:displayName,UserPrincipalName:userPrincipalName,ObjectId:id}" \
12 --output table 2>&1; then
13 echo "User found by UPN"
14else
15 echo "User not found by UPN. Continuing search..."
16fi
17
18# Step 3: List all users to see available UPNs
19echo "Listing all users in tenant..."
20az ad user list \
21 --query "[].{DisplayName:displayName,UserPrincipalName:userPrincipalName,ObjectId:id}" \
22 --output table
23
24# Step 4: Search users by display name
25DISPLAY_NAME="John Doe"
26echo "Searching for user by display name: ${DISPLAY_NAME}..."
27az ad user list \
28 --filter "displayName eq '${DISPLAY_NAME}'" \
29 --query "[].{DisplayName:displayName,UserPrincipalName:userPrincipalName,ObjectId:id}" \
30 --output table
31
32# Step 5: Search users by email address
33EMAIL="user@example.com"
34echo "Searching for user by email: ${EMAIL}..."
35az ad user list \
36 --filter "mail eq '${EMAIL}' or otherMails/any(x:x eq '${EMAIL}')" \
37 --query "[].{DisplayName:displayName,UserPrincipalName:userPrincipalName}" \
38 --output table
39
40# Step 6: Get user by object ID (if you have it)
41OBJECT_ID="12345678-1234-1234-1234-123456789012"
42echo "Searching for user by object ID: ${OBJECT_ID}..."
43if az ad user show \
44 --id ${OBJECT_ID} \
45 --query "{DisplayName:displayName,UserPrincipalName:userPrincipalName}" \
46 --output table 2>&1; then
47 echo "User found by object ID"
48else
49 echo "User not found by object ID"
50fi
51
52# Step 7: Verify UPN format
53echo "Verifying UPN format..."
54if [[ ${UPN} =~ ^[^@]+@[^@]+$ ]]; then
55 echo "UPN format is valid: ${UPN}"
56else
57 echo "ERROR: Invalid UPN format"
58 echo "Required format: user@domain"
59 echo "Example: john.doe@contoso.com"
60fi
61
62# Step 8: Instructions for checking deleted users
63echo ""
64echo "To check for deleted users:"
65echo " 1. Go to Azure Portal > Azure AD > Users > Deleted users"
66echo " 2. Search for the user by name or UPN"
67echo " 3. If found, click 'Restore user' to recover within retention period"↗Related Errors
Provider Information
This error code is specific to AZURE services. For more information, refer to the official AZURE documentation.