Jaa


Override default error messages

You can hide the Power BI embedded analytics default error messages on reports, and instead show custom error messages that fit your app design.

For example, you could replace this default error dialog:

Screenshot showing the Power BI embedded analytics default error dialog.

With this custom error dialog:

Screenshot showing a custom error dialog.

How to override errors

To use custom error messages, first hide the default Power BI embedded analytics error messages by setting the hideErrors property to true in the Power BI embedded analytics configuration object. This configuration for powerbi.embed(element, config) also includes other settings and options. For more information, see Configure report settings.

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

When you hide the default error messages, error dialogs and messages no longer appear if errors occur. For your app's users to get consistent and helpful responses when errors occur, you're responsible for handling error events.

To handle errors, first get the errors by listening on the error event:

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

The level property on the IError interface lets you specify which types of errors to handle:

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,
}

Fatal errors are the most serious error type, because they make the report unresponsive. Make sure to handle Fatal errors to prevent end users from facing unresponsive or broken reports with no error messaging.

Example

The following code example demonstrates how you can override errors by listening to and handling error events. The example doesn't show the newAccessToken or error.detailedMessage functions. Implement your own functions where indicated.

// Embed the loadConfiguration that hides the default errors.
let 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.
let embedContainer = $('#embedContainer')[0];

// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, config);

// Set report.off to remove any pre-existing error event handler.
report.off("error");

// Set report.on to add the new error event handler.
report.on("error", function(event) {
    const error = event.detail;

    // If the error level isn't Fatal, log the error and continue.
    if (error.level !== models.TraceType.Fatal) {
        console.error(error);
        return;
    }

    // If the Fatal error is TokenExpired, refresh the token.
    if (error.message === models.CommonErrorCode.TokenExpired) {
        // Implement your own function here.
        let newAccessToken = refreshToken();
        
        // Set the new access token.
        report.setAccessToken(newAccessToken);
    } else {
        // If the error isn't TokenExpired, show the custom
        // dialog with detailed error message in the iframe.
        // Implement your own function here.
        showError(error.detailedMessage);
    }
});