Overriding Error Experience

ℹ️ This wiki has been deprecated
All our Client APIs documentation and references can be found in the new Power BI embedded analytics Client APIs documentation set. For the content of this article see Override default error messages.

Overriding Error messages

You can now hide default error messages on Embedded reports and show your own error message on top of the iframe. You should use this feature if you want to show your own custom errors that fit your app design instead of the default errors currently available.
For example, you can implement this custom error dialog:

Instead of this default error:

In order to override default error messages you need to set 'hideErrors' property in loadConfiguration to true:

var config= {
    type: 'report',
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    id: embedReportId,
    permissions: permissions,
    settings: {
        hideErrors: true
    }
};

When you hide the error messages you become responsible for error treatment. This means that no error dialog/page will be shown when an error occurs. If you don't handle the errors your users can face broken/unexpected behavior when an error occurs.
To get the errors you need to listen on the 'error' event and handle the coming errors:

report.off("error");
report.on("error", function(event) {
    // Handle Errors
});

To make it easier to handle errors we have added the 'level' property to the IError object:

interface IError {
    message: string;
    detailedMessage?: string;
    errorCode?: string;
    level?: TraceType;
    technicalDetails?: ITechnicalDetails;
}

enum TraceType {
    Information = 0,
    Verbose = 1,
    Warning = 2,
    Error = 3,
    ExpectedError = 4,
    UnexpectedError = 5,
    Fatal = 6,
}

The most important level is 'Fatal'. A 'Fatal' error refers to an error that makes the report unresponsive. It is very recommended to treat these errors, if you won't treat these errors the end user will face an unresponsive or broken report with no error message.
In the following example we demonstrate how you can override Errors by listening and handling 'error' events:

// Get models. models contains enums that can be used
const models = window['powerbi-client'].models;

// Get embed application token from session
var accessToken = GetSession(SessionKeys.AccessToken);

// Get embed URL from session
var embedUrl = GetSession(SessionKeys.EmbedUrl);

// Get report Id from session
var embedReportId = GetSession(SessionKeys.EmbedId);

// We give the user View permissions
var permissions = models.Permissions.View;

// Embed configuration used to describe the what and how to embed
// This object is used when calling powerbi.embed
// This also includes settings and options such as filters
// You can find more information at https://github.com/Microsoft/PowerBI-JavaScript/wiki/Embed-Configuration-Details
var config= {
    type: 'report',
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    id: embedReportId,
    permissions: permissions,
    settings: {
        hideErrors: true
    }
};

// Get a reference to the embedded report HTML element
var embedContainer = $('#embedContainer')[0];
// Embed the report and display it within the div container
var report = powerbi.embed(embedContainer, config);

// Report.off removes a given event handler if it exists.
report.off("error");

// Report.on will add an event handler that handles errors.
report.on("error", function(event) {
    const error = event.detail;

    // If error is not Fatal log the error and continue
    if(error.level !== models.TraceType.Fatal) {
        console.error(error);
	return;
    }

    // if the error is TokenExpired refresh the token
    // else, show error dialog
    if(error.message === models.CommonErrorCode.TokenExpired) {
        // refresh token
	// this function is not implemented as part of this solution
	// you can implement your own function here
	var newAccessToken = refreshToken();
		
	// Get a reference to the embedded report HTML element
	var embedContainer = $('#embedContainer')[0];
		
	// Get a reference to the embedded report.
	var report = powerbi.get(embedContainer);
		
	// Set new access token
	report.setAccessToken(newAccessToken);
    } else {
	// show error dialog with detailed message from error over the iframe
	// this function is not implemented as part of this solution
	// you can implement your own function here
	showError(error.detailedMessage);
    }
});