Troubleshoot your embedded application

This article discusses some common issues you may get when embedding content from Power BI.

Tools to troubleshoot

Fiddler Trace

Fiddler is a free tool from Telerik that monitors HTTP traffic. You can see the traffic with the Power BI APIs from the client machine. This tool may show errors and other related information.

F12 in Browser for front-end debugging

F12 launches the developer window within your browser. This tool provides the ability to look at network traffic and other information.

Extract error details from Power BI response

This code snippet shows how to extract the error details from HTTP exception:

public static string GetExceptionText(this HttpOperationException exc)
{
    var errorText = string.Format("Request: {0}\r\nStatus: {1} ({2})\r\nResponse: {3}",
    exc.Request.Content, exc.Response.StatusCode, (int)exc.Response.StatusCode, exc.Response.Content);
    if (exc.Response.Headers.ContainsKey("RequestId"))
    {
        var requestId = exc.Response.Headers["RequestId"].FirstOrDefault();
        errorText += string.Format("\r\nRequestId: {0}", requestId);
    }

    return errorText;
}

We recommend logging the Request ID (and error details for troubleshooting). Provide the Request ID when approaching Microsoft support.

App registration

App registration failure

Error messages within the Azure portal or the Power BI app registration page mention insufficient privileges. To register an application, you must be an admin in the Azure AD tenant or application registrations must be enabled for non-admin users.

Power BI Service doesn't appear in the Azure portal when registering a new App

At least one user must be signed up for Power BI. If you don't see Power BI Service listed within the API list, no user is signed up for Power BI.

What is the difference between application object ID and principal object ID?

When you register an Azure AD app, there are a two parameters called object ID. This section explains the purpose of each parameter, and how to obtain it.

REST API

API call returning 401

A fiddler capture may be required to investigate further. The required permission scope may be missing for the registered application within Azure AD. Verify the required scope is present within the app registration for Azure AD within the Azure portal.

API call returning 403

A fiddler capture may be required to investigate further. There could be several reasons for a 403 error.

• The user has exceeded the amount of embed token that can be generated on a shared capacity. Purchase Azure capacities to generate embed tokens and assign the workspace to that capacity. See Create Power BI Embedded capacity in the Azure portal.
• The Azure AD auth token expired.
• The authenticated user isn't a member of the group (workspace).
• The authenticated user isn't an admin of the group (workspace).
• The authenticated user doesn't have permissions. Permissions can be updated using refreshUserPermissions API
• The authorization header may not be listed correctly. Make sure there are no typos.

The backend of the application may need to refresh the auth token before calling GenerateToken. For more information, see Refresh the access token.

GET https://wabi-us-north-central-redirect.analysis.windows.net/metadata/cluster HTTP/1.1
Host: wabi-us-north-central-redirect.analysis.windows.net
...
Authorization: Bearer eyJ0eXAiOi...
...

HTTP/1.1 403 Forbidden
...

{"error":{"code":"TokenExpired","message":"Access token has expired, resubmit with a new access token"}}

How to fix timeout exceptions when using import and export APIs?

When you're sending a Power BI REST API request, it might arrive at a cluster that doesn't contain your tenant's data. In such cases, redirecting the request may fail due to a timeout.

To fix the timeout exception, you can resend the request with the preferClientRouting parameter set to true. If your request arrives at the wrong cluster, the Power BI service returns a 307 Temporary Redirect HTTP response. In such cases, you need to redirect your request to the new address specified in the response HTTPS Location header.

Authentication

Authentication failed with AADSTS70002 or AADSTS50053

(AADSTS70002: Error validating credentials. AADSTS50053: You've tried to sign in too many times with an incorrect User ID or password)

If you're using Power BI Embedded and using Azure AD Direct authentication, and you're receiving messages logging in such as error:unauthorized_client, error_description:AADSTS70002: Error validating credentials. AADSTS50053: You've tried to sign in too many times with an incorrect User ID or password, that is because direct authentication is no longer in use.

There's a way to turn this back on using an Azure AD Policy that is scoped to the organization or a service principal.

We recommend you enable this policy only as a per-app basis.

To create this policy, you need to be a Global Administrator for the directory where you're creating the policy and assigning. Here is a sample script for creating the policy and assigning it to the SP for this application:

1. Install the Azure AD Preview PowerShell Module.

2. Run the following PowerShell commands line-by-line (making sure the variable $sp doesn't have more than one application as a result).

Connect-AzureAD

$sp = Get-AzureADServicePrincipal -SearchString "Name_Of_Application"

$policy = New-AzureADPolicy -Definition @("{`"HomeRealmDiscoveryPolicy`":{`"AllowCloudPasswordValidation`":true}}") -DisplayName EnableDirectAuth -Type HomeRealmDiscoveryPolicy -IsOrganizationDefault $false

Add-AzureADServicePrincipalPolicy -Id $sp.ObjectId -RefObjectId $policy.Id 

After assigning the policy, wait approximately 15-20 seconds for propagation before testing.

Generate token fails when providing effective identity

GenerateToken can fail, with effective identity supplied, for a few different reasons.

• Dataset doesn't support effective identity
• Username wasn't provided
• Role wasn't provided
• DatasetId wasn't provided
• User doesn't have the correct permissions

To verify which it is, try the steps below.

• Execute get dataset. Is the property IsEffectiveIdentityRequired true?
• Username is mandatory for any EffectiveIdentity.
• If IsEffectiveIdentityRolesRequired is true, Role is required.
• DatasetId is mandatory for any EffectiveIdentity.
• For Analysis Services, the master user has to be a gateway admin.

AADSTS90094: The grant requires admin permission

Symptoms:
When a non-admin user tries to sign in to an application for the first time while granting consent, then gets one of the following errors:

• ConsentTest needs permission to access resources in your organization that only an admin can grant. Ask an admin to grant permission to this app before you can use it.

• AADSTS90094: The grant requires admin permission.

  

An admin user can sign in and grant consent successfully.

Root cause:
User consent is disabled for the tenant.

Several fixes are possible:

Enable user consent for the entire tenant (all users, all applications)

1. In the Azure portal, navigate to "Azure Active Directory" => "Users and groups" => "User settings"

2. Enable the "Users can consent to apps accessing company data on their behalf" setting and save the changes

   

Grant permissions to the application by an admin - either for the entire tenant or a specific user.

CS1061 error

Download Microsoft.IdentityModel.Clients.ActiveDirectory if you experience an "'AuthenticationContext' does not contain a definition for 'AcquireToken' and no accessible 'AcquireToken' accepting a first argument of type 'AuthenticationContext' could be found (are you missing a using directive or an assembly reference?)" error.

Azure AD token for a different tenant (guest user)

When you embed for your organization, to allow Azure AD guest users access to your content, you need to specify the tenant ID in the authorityUri parameter.

• URL for authenticating in your organization's tenant:

  https://login.microsoftonline.com/common/v2.0

• URL for authenticating a guest Azure AD user:

  https://login.microsoftonline.com/<tenant ID>

To find your tenant ID, you can use the instructions in Find the Microsoft Azure AD tenant ID and primary domain name.

For more information, see How to: Sign in any Azure Active Directory user using the multi-tenant application pattern.

Data sources

ISV wants to have different credentials for the same data source

A data source can have a single set of credentials for one master user. If you need to use different credentials, create additional master users. Then, assign the different credentials in each of the master users contexts, and embed using the Azure AD token of that user.

Troubleshoot your embedded application with the IError object

Use the IError object returned by the error event from the JavaScript SDK to debug your application and better understand the cause of your errors.

After acquiring the IError object, you should look at the appropriate common errors table that fits the embed type you're using. Compare the IError properties with the ones in the table and find the possible reason(s) for the failure.

Typical errors when embedding for Power BI users

Typical errors when embedding for non-Power BI users (using an Embed Token)

Datasets

Manage which portion of the data your users can see

Any user with read permissions for a dataset can see the entire schema (tables, columns and measures) and all the data. You cannot separately control viewing permissions to raw and aggregated data in the same dataset.

To manage which portion of the data your users can view, use one of these methods:

• Row-level filtering using Power BI row-level security (RLS).

• Object level security (OLS).

• Separate the data into different datasets. For example, you can create a dataset that only contains aggregated data and give your users access to that dataset only.

Content rendering

To resolve rendering issues in embedded Power BI items (such as reports and dashboards), review this section.

Verify that the Power BI item loads in Power BI service

To rule out issues with your application or the embedding APIs, verify that the item can be viewed in the Power BI service (powerbi.com).

Verify that the Power BI item loads in the Power BI embedded analytics playground

To rule out issues with your application, verify that the Power BI item can be viewed in the Power BI embedded analytics playground.

Verify that your access token didn't expire

For security purposes, access tokens (An Azure AD token or an embed token) have a limited lifetime. You should constantly monitor your access token and refresh it if needed. For more information see Refresh the access token.

Performance

To get the best performing embedded content, we recommend that you follow the Power BI embedded analytics best practices.

Embed setup tool

You can go through the Embedding setup tool to quickly download a sample application. Then you can compare your application to the sample.

Prerequisites

Verify that you have all the proper prerequisites before using the Embedding setup tool. You need a Power BI Pro account and a Microsoft Azure subscription.

• If you're not signed up for Power BI Pro, sign up for a free trial before you begin.
• If you don't have an Azure subscription, create a free account before you begin.
• You need to have your own Azure Active Directory tenant setup.
• You need Visual Studio installed (version 2013 or later).

Common Issues

Some common issues you might encounter while testing with the Embed setup tool are:

Using the Embed for your customers sample application

If you're working with the Embed for your customers experience, save and unzip the PowerBI-Developer-Samples.zip file. Then open the PowerBI-Developer-Samples-master\App Owns Data folder and run the PowerBIEmbedded_AppOwnsData.sln file.

When selecting Grant permissions (the Grant permissions step), you get the following error:

AADSTS70001: Application with identifier <client ID> wasn't found in the directory <directory ID>

The solution is to close the popup, wait a few seconds and try again. You might need to repeat this action a few times. A time interval causes the issue from completing the application registration process to when it's available to external APIs.

The following error message appears when running the sample app:

Password is empty. Please fill password of Power BI username in web.config.

This error occurs because the only value that isn't being injected into the sample application is your user password. Open the Web.config file in the solution and fill the pbiPassword field with your user's password.

If you get the error - AADSTS50079: The user is required to use multi-factor authentication.

Need to use an AAD account that doesn't have MFA enabled.

Using the Embed for your organization sample application

If you're working with the Embed for your organization experience, save and unzip the PowerBI-Developer-Samples.zip file. Then open the PowerBI-Developer-Samples-master\User Owns Data\integrate-report-web-app folder and run the pbi-saas-embed-report.sln file.

When you run the Embed for your organization sample app, you get the following error:

AADSTS50011: The reply URL specified in the request doesn't match the reply URLs configured for the application: <client ID>

This error is because the redirect URL specified for the web-server application is different from the sample's URL. If you want to register the sample application, then use https://localhost:13526/ as the redirect URL.

If you'd like to edit the registered application, then learn how to update the Azure AD-registered application, so the application can provide access to the web APIs.

If you would like to edit your Power BI user profile or data, then learn how to edit your Power BI data.

If you get the error - AADSTS50079: The user is required to use multi-factor authentication.

Need to use an AAD account that doesn't have MFA enabled.

For more information, please see Power BI Embedded FAQ.

More questions? Try the Power BI Community

If you require further assistance, then contact support or create a support ticket via the Azure portal and provide the error messages you encounter.

Next steps

For more information, see FAQs.

More questions? Try the Power BI Community