How do I resolve issues in my embedded Amazon Quick dashboards?

Resolution

Prerequisites:

• Confirm that you have Amazon Quick Enterprise edition. You can only embed API operations in the Enterprise edition.
• Make sure that you granted the API caller role the AWS Identity and Access Management (IAM) quicksight:GenerateEmbedUrlForRegisteredUser or quicksight:GenerateEmbedUrlForAnonymousUser permissions to embed URLs.
• Verify that you activated both Reader Session Capacity pricing and Amazon Q in Amazon Quick capacity plans to embed Amazon Q.
  Note: To activate the plans, open the Amazon Quick console. From the navigation bar, choose the down arrow, choose Manage account, and then, choose Manage subscriptions.

Refused to connect error

If you are missing the domain in the allow list, then you receive an error message similar to the following:

"aa-example-1.quicksight.aws.amazon.com refused to connect"

To resolve this error, complete the following steps:

1. Open the Amazon Quick console.
2. From the navigation bar, choose the down arrow, and then choose Manage account.
3. Choose Manage domains.
4. In the Domain field, enter your host URL.
   Note: HTTPS is required. http://localhost is the only exception. https://www.example.com and https://example.com are separate entries, and you must register individually. Register domains in Amazon Quick for the same AWS Region that your dashboard exists.
5. Choose Add.

If you include AllowedDomains in a GenerateEmbedUrlFor* API operation, then Amazon Quick ignores the allow list for that request and only permits the domains specified in the parameter.

You can specify up to 3 domains, including http://localhost. Check the requestParameters in the corresponding AWS CloudTrail event to verify that the values passed.

Note: Subdomains aren't automatically included. If you register a domain in Amazon Quick, then select Include subdomains to allow the subdomains. If you use the AllowedDomains parameter, then explicitly list each subdomain.

Frame-ancestors error

If you specify the Amazon Quick console URL directly in an iframe, then the iframe can't load on the page and you receive the following error message:

"Frame-ancestors 'none'"

To resolve this issue, embed the URL that GenerateEmbedUrlFor* API operation generates.

Refused to frame error

If you don't specify that your host page's content security policy (CSP) allows Amazon QuickSight resources, then your host application blocks your CSP and you might get the following error message:

"Refused to frame 'https://aa-example-1.quicksight.aws.amazon.com/' because an ancestor violates the following Content Security Policy directive: "frame-ancestors'self'"

To resolve this error, add the following directives to your web server's Content-Security-Policy HTTP response header:

Content-Security-Policy: frame-src 'self' https://.quicksight.aws.amazon.com; connect-src 'self' https://.quicksight.aws.amazon.com wss://*.quicksight.aws.amazon.com

Note: Use wss:// for real-time features including Generative Q&A response streaming. If you are missing this directive, then the CSP blocks the feature.

If you set the Cross-Origin-Embedder-Policy to require-corp, then the embed feature might be blocked. To resolve this issue, remove the Cross-Origin-Embedder-Policy header from your server configuration. Or, you can set the policy to unsafe-none. For more information, see Cross-Origin-Embedder-Policy on the MDN website.

Embedding failed error

The bearer token in the embed URL must be used in the initial request within 5 minutes that you generate. If you embed an expired URL, then you receive the following error message:

"Embedding failed because of invalid URL or authorization code"

To resolve this error, specify the sessionLifetimeInMinutes parameter. If you don't specify a value, then the default is 10 hours. To prevent an expired URL, take one of the following actions:

• Set the GenerateEmbedUrlFor* API operation to call only when the user navigates to the page that contains the embedded dashboard.
• Set a timer to regenerate the URL before the 5-minute window expires if you pre-generate the URL in the background.
  Note: In cross-AWS account environments, you must call the API operation from the account that owns the Amazon QuickSight resources.

InvalidParameterValueException error

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

If you receive the InvalidParameterValueException error or see a blank screen, then take the following actions:

• Confirm that you specified GenerativeQnA and InitialTopicId in ExperienceConfiguration.
• To verify that the calling user has permissions on the topic, run the following describe-topic-permissions AWS CLI command:

  aws quicksight describe-topic-permissions
  --aws-account-id 123456789012
  --topic-id topic_id

  Note: Replace 123456789012 with your account ID and topic_id with your topic ID.
• To grant permissions, run the following update-topic-permissions AWS CLI command:

  aws quicksight update-topic-permissions
  --aws-account-id 123456789012
  --topic-id topic_id

  Note: Replace 123456789012 with your account ID and topic_id with your topic ID.

You can't activate full-screen mode

To implement full-screen mode, call the browser requestFullscreen() API operation on the container element. Then, set the frameOptions.width and frameOptions.height parameters to 100%.

You can't see the features in embedded dashboards

By default, Amazon QuickSight hides or overlays features in embedded dashboards. To turn on or adjust the features, use the keys in the contentOptions object of the Embedding SDK.