How do I resolve asset bundle failures in Quick Sight?

Resolution

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.

Identify the cause of the asset bundle failure

To identify the cause of your asset bundle failure, run the one of the following AWS CLI commands.

For an export job, run the following describe-asset-bundle-export command:

aws quicksight describe-asset-bundle-export-job 
    --aws-account-id 111122223333 
    --asset-bundle-export-job-id job-id

Note: Replace 111122223333 with your AWS account ID and job-id with your job ID.

For an import job, run the following describe-asset-bundle-import-job command:

aws quicksight describe-asset-bundle-import-job 
    --aws-account-id 111122223333 
    --asset-bundle-import-job-id job-id

Note: Replace 111122223333 with your account ID and job-id with your job ID.

Based on the failure that's stated in the command's output, use the following resolution steps to resolve the issue.

There are missing parameters in the StartAssetBundleImportJob request

You get the following error message:

"DataSourceCredentials field is incorrectly set"

The preceding error message occurs because of one of the following issues in the StartAssetBundleImportJob request:

• The necessary credentials are missing.
• The value for DataSourceId doesn't match the data source ID in the bundle.

Add the missing credentials

If the credentials are missing, then add them to the request template.

Note: To add the missing credentials, you must have secretsmanager:GetSecretValue and secretsmanager:DescribeSecret permissions on the AWS Secrets Manager secret.

For each data source in the bundle, use one of the following templates.

Inline username and password:

"Credentials": {
    "CredentialPair": {
        "Username": "username",
        "Password": "password"
    }
}

Note: Replace username with your username and password with your password.

Secrets Manager secret Amazon Resource Name (ARN):

"Credentials": {
    "SecretArn": "arn:aws:secretsmanager:aa-example-1:111122223333:secret:secret-name"
}

Note: Replace aa-example-1 with your AWS Region, 111122223333 with your account ID, and secret-name with your secret name.

Change the DataSourceID value

Change the DataSourceId value in your override so that it matches the data source ID in the bundle.

To find the data source ID, download the .qs bundle file from the export job's download URL. Then, extract the zip file and open the data source JSON file. The DataSourceId field contains the ID for your override. If you used ResourceIdOverrideConfiguration.PrefixForAllResources, then prepend the prefix to the data source ID in your override.

Make sure that all DataSourceParameters values in the override match the data source type.

The bundle dependency is missing

You get the following error message:

"Invalid dataSourceArn"

This issue can occur because the bundle dataset references a data source that you didn't include in the bundle and doesn't exist in the destination account.

To resolve this issue, complete the following steps:

1. Run the following start-asset-bundle-export-job AWS CLI command to export the bundle with the dependencies included:

   aws quicksight start-asset-bundle-export-job 
       --aws-account-id 111122223333 
       --asset-bundle-export-job-id new-job-id 
       --resource-arns 555555555555 
       --include-all-dependencies 
       --include-permissions 
       --export-format QUICKSIGHT_JSON

   Note: Replace 111122223333 with your source account, new-job-id with your job ID, and 555555555555 with your resource ARN.
2. Either run the StartAssetBundleImportJob API operation to run the import against the new bundle. Or, run the following create-data-source AWS CLI command to create the data source in the destination account:

   aws quicksight create-data-source 
       --aws-account-id 444455556666 
       --data-source-id id-from-bundle 
       --name name 
       --type service-type 
       --data-source-parameters file://params.json 
       --credentials file://creds.json 
       --permissions file://perms.json

   Note: Replace 444455556666 with your destination account ID and id-from-bundle with the data source ID from the exported bundle. Also, replace name with a display name for the data source and service-type with the data source type that matches your source. The create-data-source command returns a list of all supported data types.
3. (Optional) If you use PrefixForAllResources to import the asset bundle, then you must use the prefixed ID for created data.

The data source creation failed

If your import creates a data source in the destination account and the status is CREATION_FAILED, then your connection test or validation failed.

To identify the reason for the failure, run the following describe-data-source AWS CLI command:

aws quicksight describe-data-source 
    --aws-account-id 444455556666 
    --data-source-id data-source-id

Note: Replace 444455556666 with your destination account and data-source-id with your data source ID.

Review the output, and then complete the resolution based on the error message that you received.

The workgroup isn't found

You get the following error message:

"WorkGroup is not found (Athena)"

To resolve this issue, run the import command with the --override-parameters flag and specify an Athena workgroup that's in the destination account.

Example override parameter flag:

--override-parameters '{
  "DataSources": [{
    "DataSourceId": "id-from-bundle",
    "DataSourceParameters": {
      "AthenaParameters": {
        "WorkGroup": "destination-workgroup",
        "RoleArn": "string"

      }
    }
  }]
}'

Note: Replace data-source-id with your data source ID and destination-workgroup with a workgroup that's in the destination account. If your Athena data source uses a custom role, then include RoleArn in AthenaParameters.

Quick Sight didn't assume the IAM role

You get the following error message:

"Could not assume role / IAM_ROLE_NOT_AVAILABLE"

To resolve this issue, override the role ARN with a destination account role that has the required permissions and trusts the Quick Sight service.

There's a connection failure

You get the following error message:

"CONNECTION_FAILURE / UNRESOLVABLE_HOST"

To resolve this issue, override the host, port, database, or cluster ID to match the destination environment.

The data source authorization failed

You get the following error message:

"DATA_SOURCE_AUTH_FAILED / PASSWORD_AUTHENTICATION_FAILURE"

To resolve this issue, rotate the credentials in the override or update the secret in Secrets Manager.

To delete the failed data source before you reimport, run the following delete-data-source AWS CLI command:

aws quicksight delete-data-source 
    --aws-account-id 444455556666 
    --data-source-id data-source-id

Note: Replace 44445556666 with your destination account and data-source-id with your data source ID.

Then, run the import again with the corrected --override-parameters.

If your import fails, then set --failure-action to ROLLBACK to automatically delete partially created assets from the destination account.

The manifest file failed to parse

You get the following error message:

"Failed to parse the manifest file"

This issue can occur when your import bundle includes an Amazon Simple Storage Service (Amazon S3) data source that uses a manifest file that the destination account can't parse.

To resolve the issue, first confirm that the manifest is a valid UTF-8 JSON with a fileLocations array.

If the manifest is in a source-only bucket, then copy the bucket to the destination account and override the manifest location in the import.

Add the following request syntax to the import job:

"S3Parameters": {
    "ManifestFileLocation": {
        "Bucket": "amzn-s3-demo-desination-bucket",
        "Key": "key/to/manifest.json"
    }
}

Note: Replace amzn-s3-demo-destination-bucket with your destination bucket ARN and key with your AWS Key Management Service (AWS KMS) key.

There's a manifest file permissions error

You get the following error message:

"Insufficient permission to access the manifest file"

This issue occurs because your import bundle includes an Amazon S3 data source that uses a manifest file that the destination account can't read.

To resolve this issue, complete the following steps in the destination account:

1. Open Amazon Quick.
2. Choose Manage account.
3. Choose AWS resources, and then select the S3 bucket that contains the manifest file.
4. Choose Save.

The S3GetObject permission is missing

You get the following error message:

"Insufficient permission"

This issue occurs because you ran the StartAssetBundleImportJob API operation without the S3:GetObject permission on the bundle .qs file.

To resolve this issue, add the following statement to the AWS Identity and Access Management (IAM) policy that's attached to your IAM user or role:

{
  "Effect": "Allow",
  "Action": "s3:GetObject",
  "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/path-to-bundle/*.qs"
}

Note: Replace amzn-s3-demo-bucket with your bucket name and path-to-bundle with the resource path.

The VPC subnets aren't valid VPC connection errors

You get the following error message:

"The provided subnets are invalid"

This issue can occur when you use a virtual private cloud (VPC) connection to import the bundle. Either the subnet or security group IDs from the source account don't exist in the destination account.

To resolve this issue, run the following command to override VPCConnections in the import API operation:

"VPCConnections": [
    {
        "VPCConnectionId": "id-from-bundle",
        "SubnetIds": ["subnet-...", "subnet-..."],
        "SecurityGroupIds": ["sg-..."],
        "RoleArn": "arn:aws:iam::444455556666:role/aws-quicksight-service-role-v0"
    }
]

Note: Replace id-from-bundle with your bundle ID and 444455556666 with your destination account ARN.

To check that the VPC connection role has the required Amazon Elastic Compute Cloud (Amazon EC2) network permissions, complete the following steps:

1. Open the IAM console.

2. In the navigation pane, choose Roles.

3. Search for the role that's specified in the RoleArn of your VPC connection override.

4. Review the attached policies to confirm that they include the following permissions:

   {  
   "Effect": "Allow",
     "Action": [
       "ec2:CreateNetworkInterface",
       "ec2:ModifyNetworkInterfaceAttribute",
       "ec2:DeleteNetworkInterface",
       "ec2:DescribeSubnets",
       "ec2:DescribeSecurityGroups"
     ],
     "Resource": "*"
   }

5. If permissions are missing, then choose Add permissions and create an inline policy with the preceding permissions.

Confirm that the database that Quick Sight is trying to reach allows inbound traffic from the security group that's attached to the VPC connection.

The dataset is out of sync

You get the following error message:

"Derived output schema is no longer compatible with the expected output columns"

This issue occurs when you import a source dataset that's out of sync.

To resolve this issue, complete the following steps in the source account:

1. Open Amazon Quick.
2. In the navigation pane, choose Data.
3. Open the dataset.
4. Choose Edit dataset.
5. Sync the dataset.
6. Choose Save and publish.
7. To confirm that the dataset sync is successful, run the following commands.
   For the export job status, run the following describe-asset-bundle-export-job command:

   aws quicksight describe-asset-bundle-import-job --aws-account-id 111122223333 --asset-bundle-import-job-id asset_bundle_ID

   Note: Replace 111122223333 with your account ID and asset_bundle_ID with your asset bundle import job ID.
   For the import job status, run the following describe-asset-bundle-import-job command:

   aws quicksight describe-asset-bundle-export-job --aws-account-id 111122223333  --asset-bundle-export-job-id assetbundle_id

   Note: Replace 111122223333 with your account ID and assetbundle_id with your asset bundle job ID.

The bundle contains an empty string

You get the following validation error message:

"Value ' ' at 'definition.sheets...customLabel' failed to satisfy constraint"

This issue occurs because the bundle contains an empty string.

To resolve this issue, edit the visual and clear or replace the empty property in the source analysis. Then, export the asset bundle again and retry the import job.

It's a best practice to set OverrideValidationStrategy.StrictModeForAllResources to true in the import API operation.

There's an internal service issue

You get the following error message:

"InternalServiceError: Unexpected internal service error"

If your import job fails after multiple reimports, then contact AWS Support.

The data source type isn't supported

You get the following error message:

"The data set type is not supported through API yet"

This issue occurs because your export job includes a dataset that uses an unsupported file upload.

To resolve this issue, manually recreate the data source in the destination account. You can either run the following create-data-source AWS CLI command or use the Quick console to recreate the data source.

aws quicksight create-data-source --aws-account-id 111122223333 --data-source-id datasource_id --name datasource_name --type datasource_type

Note: Replace 111122223333 with your account ID, datasource_id with your data source ID, datasource_name with your data source name, datasource_type with your data source type.

Run the export job and include only the dependent assets that reference the data source.

The imported assets aren't visible in the destination account

The import might succeed but dashboards or datasets aren't visible on the Amazon Quick console in the destination account. This occurs when the asset bundle imports didn't propagate the principal permissions.

To resolve this issue, take one of the following actions:

• Run the import with the --override-permissions flag to grant permissions to the imported assets in a single job.

• Run the following update-dashboard-permissions AWS CLI command to update the dashboard permissions:

  aws quicksight update-dashboard-permissions --aws-account-id 111122223333 --dashboard-id dashboard_id

  Note: Replace 111122223333 with your account ID and dashboard_id with your dashboard ID.

• Run the following update-analysis-permissions AWS CLI command to update the analysis permissions:

  aws quicksight update-analysis-permissions --aws-account-id 111122223333 --analysis-id analysis_id

  Note: Replace 111122223333 with your account ID and analysis_id with your analysis ID.

• Run the following update-data-set-permissions AWS CLI command to update the dataset permissions:

  aws quicksight update-data-set-permissions --aws-account-id 111122223333 --data-set-id dataset_id

  Note: Replace 111122223333 with your account ID and dataset_id with your dataset ID:

• Run the following update-data-source-permissions AWS CLI command to update the data source permissions:

  aws quicksight update-data-source-permissions --aws-account-id 123456789012 --data-source-id datasource_id

  Note: Replace 111122223333 with your account ID and datasource_id with your data source ID.

Related information

Automate and accelerate your Amazon QuickSight asset deployments using the new APIs