How do I troubleshoot data loading issues in QuickSight dashboards and visuals?

Resolution

Resolve visual query timeouts

QuickSight enforces a 2-minute timeout to generate a visual and a 45-second timeout for data preparation. To resolve a timeout, reduce the work that the visual requires QuickSight to do.

To move heavy calculated fields from analysis time to data preparation time, complete the following steps:

1. Open the Amazon Quick console.
2. In the navigation pane, choose Data.
3. Select the dataset.
4. Choose Edit dataset.
5. Add the calculation as a calculated field to the dataset.
   Note: Window functions such as RANK, DENSE_RANK, and PERCENTILE over large partitions might cause timeout. Pre-compute the functions in the source query or as a materialized calculated field.
6. Choose Publish. 

To reduce the data that QuickSight scans for each visual, complete the following steps:

1. Open the Amazon Quick console.
2. In the navigation pane, choose Data.
3. In the dataset, clear the columns that the visuals don't use.
4. In the analysis, add filters to the visual or sheet that scope the data.

To troubleshoot timeout errors, take the following actions:

• For direct query datasets, push predicates into the query. For more information, see How do I resolve query timeout errors in QuickSight?
• Switch the dataset from direct query to SPICE if the dataset fits within SPICE quotas. If you must keep direct query, then optimize the source query. Use EXPLAIN SQL command to find slow joins, missing indexes, or full-table scans.
• For Amazon Athena, review the top 10 performance tuning tips for Athena.
• For Amazon Redshift, make sure that you granted the user that QuickSight connects with the appropriate workload management (WLM) priority.
• Pass the parameter values into the source query. For more information, see Optimize queries using dataset parameters in Amazon QuickSight.
• Simplify the visual, and then reduce the number of rows, columns, metrics, subtotals, and table calculations.
  Note: If your dimension cardinality is below the cutoff, then turn off the Other category.
• Use pivot table best practices.

Resolve visual errors

If a specific visual or whole dashboard fails to render but the dataset doesn't time out, then take the following actions.

Reproduce the error

Clear cookies, and then turn off browser extensions. To try to reproduce the error, open the dashboard in a private window, in a different browser, or on a different network. If the visual loads, then the original session, cache, extension, or network caused the visual error.

Resolve can't parse SQL error

If you include fields that aren't accepted on creation, then you get the following error message:

"We can't parse this SQL syntax. If you are using custom SQL, verify the syntax and try again"

To resolve this error, check your CloudTrail logs to determine whether you created or updated the dashboard or analysis. Then, compare the failing definition with a definition that's created in QuickSight. Remove the fields that aren't present in the working definition.

Check RLS or CLS

If some only some users can see the visual on the dashboard, then check the  row-level security (RLS) or column-level security (CLS) for those users.

To check the filters, complete the following steps:

1. Open the Amazon Quick console.
2. In the navigation pane, choose Data.
3. Open the rules dataset that's attached to the parent dataset's RLS or CLS settings.
4. Confirm that the usernames, group memberships, or session-tag attribute values of the affected users match the rule rows that grant them access.

It's a best practice to use SPICE for rules dataset and to keep the rules dataset small. For embedded dashboards, use session tags for RLS with anonymous identity.

Configure your corporate network or VPN

If an error appears across users on a corporate network or VPN, then the network might block domains that QuickSight uses.

To resolve this error, make sure that your network or proxy administrator adds the following domains to the allowlist:

• *.aws.amazon.com
• amazonaws.com
• wss://*.aws.amazon.com (WebSocket, required for visual data)
• cloudfront.net
• *.quicksight.aws.amazon.com

Note: Add the same domains as exceptions to the ad blockers that you use.

Capture a HAR file

Capture an HTTP Archive (HAR) file, and look for failed requests on *.quicksight.aws.amazon.com. If you have a WebSocket failure, then the error is with your corporate proxy, firewall, or VPN. To resolve this issue, reconfigure your corporate proxy, firewall or VPN.

Refresh the dashboard

If the error only appears when you reopen the dashboard from the dashboards list, then the issue is browser session caching.

To resolve this issue, reload the page. Or, open dashboards through the direct dashboard link.

Republish the analysis

If your forecast or insight visual loads in the analysis but shows a blank screen on the published dashboard, then republish the analysis. To replace an existing dashboard, see Publishing dashboards.

Check geospatial data

If your points-on-map visual doesn't render, then confirm that you entered valid Decimal values for the latitude and longitude fields.

Reduce dashboard load time

If the dashboard loads slowly, then take the following actions.

• Get Amazon Cognito or AWS Security Token Service (AWS STS) session tokens before the page loads.
• Use RegisterUser API operation outside the embed flow to register users in advance.
• If no visual references a dataset, then remove the dataset from the analysis.
• For filter controls, use Text field for high-cardinality string columns.
• For multi-select controls, turn on the Apply button so that changes only run once the user chooses.
• Place heavy visuals later in the visual execution sequence from left to right and then top to bottom.
• Place lightweight KPIs and insight visuals at the top and heavy tables and pivots near the bottom.
• Use navigateToDashboard() or setSelectedSheetId() functions from the QuickSight embedding SDK to reuse the iframe and authentication token between dashboards and sheets.

Resolve embedded dashboard CORS or cross-origin errors

If your embedded QuickSight dashboard fails inside an iframe, then you get an error message similar to the following:

""Failed to read a named property 'href' from 'Location': Blocked a frame with origin" or generic CORS errors"

To resolve this error, take the following actions:

• If the dashboard fails in a normal session but loads in an incognito session, then the browser or third-party cookie policy caused the dashboard failure. Test the embed in a fresh browser context.
• (Optional) In Chrome, allow third-party cookies for *.quicksight.aws.amazon.com for the affected users.
• Add the embedding domain to the allowlist in the Amazon Quick console. Domains must include the scheme and port if the port is non-default.
• Use GenerateEmbedUrlForRegisteredUser API operation or GenerateEmbedUrlForAnonymousUser API operation to generate the embed URL.
• If the symptom is intermittent, then the browser session is contaminated after multiple QuickSight sessions. To resolve this issue, sign out and clear cookies for *.quicksight.aws.amazon.com, and then sign back in.
• For development troubleshooting, replicate against the Amazon QuickSight Workshops anonymous-embedding lab to isolate whether the problem is in your application code or the QuickSight configuration.

Related information

Tips and tricks for high-performant dashboards in QuickSight

Best practices for QuickSight SPICE and direct query mode

Data source quotas

I can't see my visuals (troubleshoot adding visuals)