Microsoft Entra Agent ID
Microsoft identity platform

Microsoft agent identity platform error codes

In brief

The article now routes administrators to the appropriate diagnostics for local sign-in, OAuth, Microsoft Graph, and post-token API failures. It also adds guidance on recording request details safely and clarifies blueprint-principal handling for fleet and single-instance agents.

What Entra admins need to know

Use the updated troubleshooting flow and retain the specified non-sensitive request details when investigating failures.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.


title: Microsoft agent identity platform error codes description: Learn about the Agent ID, Agent Blueprint, and Agent Identity error codes. ms.date: 12/02/202511/05/2026 ai-usage: ai-assisted ms.reviewer: ryankabir ms.topic: error-reference #Customer intent: As a developer troubleshooting errors, I want to understand the meaning and possible resolutions for the Agent ID error codes, so that I can effectively debug and fix issues in my application.

Microsoft agent identity platform error codes

This article provides a comprehensive referenceexplains Microsoft Graph errors for error codes you might encounter when working with the Microsoft agent identity platform.objects. OAuth sign-in failures and local tooling failures use different diagnostics; use the routes below before changing a directory object or its permissions.

Identify the failing layer

FailureStart here
Local browser, WAM, or missing Microsoft Graph sign-in context.Management-client sign-in. An empty Get-MgContext isn't successful authentication.
OAuth response containing AADSTS or token acquisition failure.Microsoft identity platform error codes. Confirm tenant, client ID, audience, and the scenario's required consent.
Microsoft Graph HTTP error while provisioning or updating objects.The tables in this article and Microsoft Graph error responses.
API returns 401 or 403 after a token is acquired.Your API's token validation and authorization requirements. A token request succeeding doesn't prove that its audience, scopes, roles, or resource access match the API operation.

For a failed Graph request, retain the HTTP status, error.code, error.message, request timestamp, and request-id response header. Record which operation and tenant failed, but don't include tokens, secrets, or private keys in support requests. Distinguish the object and client IDs before retrying. Don't treat every 403 as a propagation delay or grant broader permissions without diagnosing the denial.

Handling error codes in your application

Error code Description
AgentIdentity_AgentBlueprintPrincipalDoesNotExist The required agent identityFor a fleet, create the blueprint principal and check that its appId matches the blueprint. For a single-instance agent, don't create a principal; use the single-instance provisioning request, which references the blueprint principal doesn't exist for the specified agent identity blueprintobject ID.
AgentIdentity_CredentialsNotSupported Credentials are not supported for agent identities. All credentials must be added to the agent identity blueprint.
AgentIdentity_IncompatibleParentType The specified Application (AppId) isn't an Agent Blueprint. The AgentIdentityBlueprintId must be set to the AppId of a valid agent identity blueprint.
AgentIdentity_NotSupportedOnApiVersion Agent identities aren't supported on the API version used in this request.
Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…