Share via

Troubleshoot and debug your embedding code

  • Article

When developing an embedded analytics solution, you may run into errors. When this happens, you need to figure out why the error occurred.

Use the error event to debug your embedded analytics solution and better understand what caused your errors.

If there is an error you don't know how to handle, you can always search or ask a question on Stack Overflow.

Find what error occurred

An error event fires when an error occurs. You can listen to the event by using element.on(...), and then set an event handler.

report.on('error', (errorObject) => {
    ...
});

For more information about handling events, see How to handle events.

The error event returns an IError object:

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

For example, when the token expires you'll get the following error object:

{
    "message": "TokenExpired",
    "detailedMessage": "Access token has expired, resubmit with a new access token",
    "errorCode": "403"
}

For information about refreshing the access token, see Refresh the access token.

Troubleshooting

After you acquire the IError object, compare look it up in the Troubleshoot your embedded application with the IError object table, and find the possible cause(s) of the failure.

Note

There's a common errors table for Power BI users (also known as embed for your organization), and for non-Power BI users (also known as embed for your customers).

Debug in the browser's console

You can also simply debug your app in the browser's console. For instance, enter the following code snippet after you have an embed instance:

// Add a listener to 'error' events
report.on('error', (errorObject) => {
    const err = errorObject.detail;

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

Catch the APIs errors

Most of the Client APIs are async functions that return a Promise.

If you're using the async/await pattern, you should use try/catch to catch potential error. For example:

try {
    ...

    // Set a new access token
    await report.setAccessToken(newAccessToken.token);
} catch (e) {
    ...
}

If you're not using the async/await pattern, you can use the catch function to catch potential error. For example:

// Set a new access token
report.setAccessToken(newAccessToken.token).catch(e => {
    ...
});

Related content