Troubleshooting and debugging of embedded parts

Getting the IError object from 'error' event

The process of debugging & troubleshooting the embedded parts of your application, while developing or on a production application, starts with 'error' events. An 'error' event is fired when an error occurs on the loading or rendering process.
An 'error' event returns the IError object:

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

• Other errors (errors that are not loading/rendering related) can be handled by directly calling the 'catch' method after the JavaScript API function is called, they also return the IError object. An example for this scenario can be found in update settings or export data documentation. This type of errors will not be further discussed on this article.

In order to get an 'error' event, one should listen on the event using the 'on' method after embedding a report. one can simply debug his application directly from the browser console by, for example, entering the following code snippet after embedding a report:

// 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);
	
[AS] // Add a listener to 'error' events
report.on('error', (errorObject) => {
    const err = errorObject.detail;

    // Print error to console
    console.log(`Error occurred: ${err.message}. Detailed message: ${err.detailedMessage}`);
    console.log(err);
});

To simplify debugging of embedded elements, it is possible to implement a 'debug mode' as part of the application.
Here is an example for such implementation:

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

// This function retrieves query params from url
var isDebugMode = GetParameterByName('debug', window.location);

// If there is a debug url param then enter debug mode,
// listen to 'error' event and handle errors
if (isDebugMode === 'true') {
	report.on('error', (errorObject) => {
	    const err = errorObject.detail;
               
	    // Print error to console
            console.log(`Error occurred: ${err.message}. Detailed error message: ${err.detailedMessage}`);
	    console.log(err);
		
	    // Telemetry handling (it is recommended to implement telemetry for your app)
	    // telemetryService.logEvent(new ErrorEvent(err));
	});
}

Troubleshooting

Once acquired, the IError object can be used to understand what is causing the error. To do that, one should look at the appropriate common errors table, i.e, the table that fits the embed type that was used, and compare the IError properties with the ones in the table.