Troubleshooting and Debugging

In this section

Debugging your web application with the embedded view

The most convenient way to debug your web application is to use the debugging tools built into your web browser. Using the debugging tools, you can set breakpoints, examine data structures, and view console messages.

Use the non-minified version of the Embedding API v3 library

To improve web page load times and the user experience, you typically want to use the minified version of the Embedding API v3 library (tableau.embedding.3.latest.min.js). However, while you are developing your application, we recommend that you use the non-minified version of the Embedding API v3 library. You can access non-minified versions of the library by removing .min from the filename, for example, tableau.embedding.3.latest.js. The non-minified version of the library is easier to read, and includes symbol information that can help when you need to debug your embedding code.

For example, to link to the library for debugging from Tableau Cloud, you might include the following <script> block on your web page:

<script type="module" src=""></script>

To better understand and debug issues with your embedded view, set breakpoints and use console.log statements in your code, so you can see that the objects and values are returned and passed between methods. You can also use the debugging tools to drill down to examine properties and structures.

    let viz = document.getElementById("tableauViz");


The following section describes some common issue you might encounter and provides some suggestions about resolving them.


Problem: The embedded viz appears in your web application and the viz is interactive (that is, you can select marks or set filters in the viz directly), but the two-way communication is not working (that is, calls to the Embedding API v3 don’t work; your web application can’t interact with the embedded viz).

Try this

Blank iframe (Tableau viz does not appear)

Problem: In your web application there is a blank iframe where the embedded view should be. Open your debugging tools and look for any error messages.

Invalid URL error

Error: invalid-url: Failed to construct 'URL': Invalid URL

If you are getting this error, it means the the src for the embedded viz is not set correctly. The best way to get the URL that you use for the src is to click the Share button on the Tableau toolbar and then use the Copy Link button. If you were initializing the Embedding API using JavaScript (as opposed to the <tableau-Viz> web component), you might have a statement like viz.src = ''; in your code. If you were embedding the view using the web component, it might look like the the following:

  <tableau-viz id="performanceViz" src=''>
    <viz-filter field="YEAR(Date)" value="2012"></viz-filter>

Import error

If the view fails to load, open the browser debugging tools and check the console for error messages.

Uncaught SyntaxError: Cannot use import statement outside a module

Or you might see the following error:

Uncaught SyntaxError: Unexpected token 'export' 

You might see this error depending on how you are initializing and the embedding the viz. If are using JavaScript to initialize the viz, and you’ve created a separate file with your JavaScript code, where you import the library, check how you include that JavaScript file in your HTML page. You should set type="module". For example, if you import the library in a file called initialization.js:

import {
} from '';

In your HTML web page, you need to be sure to include the file using type="module".

<script type="module" src="./initialization.js"></script>

If you are using one of the Tableau web components to embed the viz and you are importing the library using script tags in your HTML code, be sure to set the type as module.

<script type="module" src=""></script>

Cross-origin request (CORS) error

Access to script at 'file:///Users/' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: `http`, `data`, `chrome`, `chrome-extension`, `chrome-untrusted`, `https`.

If you link to a local version of the Embedding API library, or load your web application from the file system, you could see this error. For the Embedding API library, you can avoid this problem by using the hosted version on the CDN: For more information about linking to the Embedding API library, see Access the Embedding API.