

# Amazon S3 integration
<a name="s3-integration"></a>

With Amazon S3 integration in Amazon Quick, you can create knowledge bases from documents stored in S3 buckets. This integration supports data ingestion capabilities for indexing and searching S3 content.

**Note**  
This guide covers Amazon S3 data ingestion integration for knowledge base creation. For Amazon S3 action connectors that perform Amazon S3 operations such as uploading, downloading, and deleting files, see [Amazon service action connectors](builtin-services-integration.md). Amazon S3 actions are only supported for Quick Automate.

## What you can do
<a name="s3-integration-capabilities"></a>

Amazon S3 users can ask questions about content stored in their Amazon S3 buckets. For example, users can inquire about key findings from documents, search for specific information across multiple file types, or analyze data patterns.

The integration enables users to quickly access and understand information from their Amazon S3 content, regardless of file location or type. It also provides contextual details such as modification dates and file metadata, contributing to more efficient information discovery and better-informed decision making.

## Before you begin
<a name="s3-integration-prerequisites"></a>

Before you set up Amazon S3 integration, make sure you have the following:
+ Amazon account with Amazon S3 access.
+ Amazon S3 bucket with documents to index.
+ Amazon Quick Enterprise subscription.
+ Necessary permissions to create Amazon S3 integrations.
+ Your administrator must grant Amazon Quick access to the Amazon S3 buckets you want to use. For more information, see [Grant Amazon Quick access to Amazon S3 buckets](s3-admin-setup.md#s3-grant-bucket-access).

**Note**  
Cross-account Amazon S3 access is only supported within the same Amazon region.

# Administrator setup
<a name="s3-admin-setup"></a>

Before users can create Amazon S3 integrations and knowledge bases, an Amazon Quick administrator must complete the following setup tasks.

## Grant Amazon Quick access to Amazon S3 buckets
<a name="s3-grant-bucket-access"></a>

Grant Amazon Quick access to the Amazon S3 buckets your organization needs. This applies whether the buckets are in the same Amazon account or a different account.

1. In the Amazon Quick admin console, under **Permissions**, choose **Amazon resources**.

1. Under **Allow access and autodiscovery for these resources**, select the **Amazon S3** checkbox.

1. Choose **Select S3 buckets**.

1. In the **Select Amazon S3 buckets** dialog, choose the tab that matches your bucket location:
   + **S3 Buckets Linked To Quick Account** – Select the buckets from the list that you want Amazon Quick to access. Selected buckets have read-only permissions by default.
   + **S3 Buckets You Can Access Across Amazon** – For cross-account buckets, make sure the account owner has authorized your account. Choose **Use a different bucket**, enter the bucket name, and choose **Add S3 bucket**.

1. (Optional) For cross-account buckets, select **Restrict bucket access to knowledge base creator** to limit access so that only the user who creates the knowledge base can use the bucket.

1. Choose **Finish**.

The selected buckets are now accessible to users during knowledge base creation.

## Prepare IAM role and policy setup
<a name="s3-integration-authentication"></a>

Amazon S3 integration uses Amazon authentication to access your Amazon S3 buckets. Prepare your IAM role and policy configuration before users set up the integration.

### Required IAM permissions
<a name="s3-integration-iam-permissions"></a>

Make sure your Amazon account has the following minimum permissions for the Amazon S3 bucket:
+ `s3:GetObject` – Read objects from the bucket.
+ `s3:ListBucket` – List bucket contents.
+ `s3:GetBucketLocation` – Get bucket region information.
+ `s3:GetObjectVersion` – Get object versions.
+ `s3:ListBucketVersions` – List bucket versions.

### Configure Amazon S3 bucket permissions for cross-account access
<a name="s3-cross-account-bucket-policy"></a>

If you're accessing Amazon S3 buckets in a different Amazon account, you must configure IAM policies in the source Amazon account.

**To configure Amazon S3 bucket permissions for cross-account access**

1. Sign in to the Amazon Management Console for the account that contains the Amazon S3 bucket.

1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. Choose the bucket that you want to grant access to.

1. Choose **Permissions**, and then choose **Bucket Policy**.

1. Add a bucket policy with the following elements:
   + `Version` – Set to "2012-10-17"
   + `Statement` – Array containing policy statements with:
     + `Sid` – "AllowQuickSuiteS3Access"
     + `Effect` – "Allow"
     + `Principal` – Amazon ARN for the Amazon Quick service role in your account. For example, the principal should look like this:` "Principal": { "AWS": "arn:aws:iam::<quick_account_id>:role/service-role/aws-quicksight-service-role-v0" }`
     + `Action` – Array of Amazon S3 permissions: s3:GetObject, s3:ListBucket, s3:GetBucketLocation, s3:GetObjectVersion, s3:ListBucketVersions
     + `Resource` – "\$1" (applies to the current key), the Amazon S3 bucket path should look like the following: `"Resource": [ "arn:aws:s3:::bucket_name"]`

1. Choose **Save changes**.

### Configure KMS key permissions (if your bucket uses encryption)
<a name="s3-kms-permissions"></a>

If your Amazon S3 bucket uses Amazon KMS encryption, complete the following steps.

**To configure KMS key permissions**

1. Open the Amazon Key Management Service (Amazon KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).

1. Choose the KMS key that is used to encrypt your Amazon S3 bucket.

1. Choose **Key policy**, and then choose **Edit**.

1. Add a statement to the key policy with the following structural elements:
   + `Sid` – "AllowQuickSuiteKMSAccess"
   + `Effect` – "Allow"
   + `Principal` – Amazon ARN for the Amazon Quick service role in your account. For example, the principal should look like this:` "Principal": { "AWS": "arn:aws:iam::<quick_account_id>:role/service-role/aws-quicksight-service-role-v0" }`
   + `Action` – Array of KMS permissions: kms:Decrypt, kms:DescribeKey
   + `Resource` – "\$1" (applies to the current key), the Amazon S3 bucket path should look like the following: `"Resource": [ "arn:aws:s3:::bucket_name"]`

1. Choose **Save changes**.

1. Wait 2-3 minutes for the policy changes to propagate.

## Configure VPC access for Amazon S3 Connector in Amazon Quick
<a name="s3-vpc-support"></a>

VPC permissions ensure Amazon Quick can only access your Amazon S3 bucket through secure VPC or VPC endpoint connections.

### Required policy change
<a name="s3-vpc-required-policy"></a>

Add this statement to your bucket access policy to allow Amazon Quick to access your bucket through VPC endpoints:

```
{
  "Sid": "Allow-Quick-access"		 	 	 ,
  "Principal": "arn:aws:iam::Quick Account:role/service-role/aws-quicksight-service-role-v0",
  "Action": "s3:*",
  "Effect": "Allow",
  "Resource": [
    "arn:aws:s3:::amzn-s3-demo-bucket",
    "arn:aws:s3:::amzn-s3-demo-bucket/*"
  ],
  "Condition": {
    "Null": {
      "aws:SourceVpce": "false"
    }
  }
}
```
+ Replace `amzn-s3-demo-bucket` with your bucket name.
+ Replace `Quick Account` with your Amazon Quick account.

The `"aws:SourceVpce": "false"` condition ensures Amazon Quick can only access your bucket through VPC endpoints, maintaining your security requirements.

### Deny policies
<a name="s3-vpc-deny-policies"></a>

If your bucket has a policy that restricts traffic to a specific VPC or VPC endpoint via Deny Policy, you must reverse this policy because deny policies take precedence over allow policies.

For example:

```
{
   "Version":"2012-10-17"		 	 	 ,                   
   "Id": "Policy1415115909152",
   "Statement": [
     {
       "Sid": "Access-to-specific-VPCE-only",
       "Principal": "*",
       "Action": "s3:*",
       "Effect": "Deny",
       "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket",
                    "arn:aws:s3:::amzn-s3-demo-bucket/*"],
       "Condition": {
         "StringNotEquals": {
           "aws:SourceVpce": "vpce-0abcdef1234567890"
         }
       }
     }
   ]
}
```

Should be reversed into:

```
{
   "Version":"2012-10-17"		 	 	 ,                   
   "Id": "Policy1415115909152",
   "Statement": [
     {
       "Sid": "Access-to-specific-VPCE-only",
       "Principal": "*",
       "Action": "s3:*",
       "Effect": "Allow",
       "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket",
                    "arn:aws:s3:::amzn-s3-demo-bucket/*"],
       "Condition": {
         "StringEquals": {
           "aws:SourceVpce": "vpce-0abcdef1234567890"
         }
       }
     }
   ]
}
```

### Best practices
<a name="s3-vpc-best-practices"></a>

**Restrict access to your Amazon Quick role**

Access policies should enforce that the caller is your Amazon Quick role ARN or, at minimum, your Amazon Quick account. This ensures that despite allowing VPC traffic, calls come only from expected sources.

### Security recommendations
<a name="s3-vpc-security-recommendations"></a>
+ Restrict policies to your Amazon Quick role for most secure traffic
+ Review your bucket policies regularly to ensure they follow the principle of least privilege

## Restrict Amazon S3 bucket access with IAM policy assignments
<a name="s3-restrict-bucket-access"></a>

You can control which Amazon S3 buckets your Amazon Quick users can use to create knowledge bases by creating IAM policies and assigning them to specific users, groups, or all users through Amazon Quick IAM policy assignments. This allows you to restrict who can create knowledge bases against specific buckets, including ACL-aware knowledge bases.

**Note**  
IAM policies assigned through Amazon Quick take precedence over Amazon resource-level policies. To ensure your access requirements are met, configure your IAM policies appropriately.

For example, you can assign a restrictive policy to specific users who need access to ACL-aware buckets, while assigning a broader policy to all users for non-ACL buckets.

### Step 1: Create an Amazon S3 access policy in IAM
<a name="s3-create-iam-policy"></a>

Create an IAM policy in the Amazon IAM console that defines which Amazon S3 buckets users can access for knowledge base creation. The following example policy grants access to two specific buckets:

```
{
    "Version": "2012-10-17"		 	 	 ,
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Action": [
                "s3:ListBucket"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1",
                "arn:aws:s3:::amzn-s3-demo-bucket-2"
            ]
        },
        {
            "Action": [
                "s3:GetObject",
                "s3:GetObjectVersion"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1/*",
                "arn:aws:s3:::amzn-s3-demo-bucket-2/*"
            ]
        },
        {
            "Action": [
                "s3:ListBucketMultipartUploads",
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1",
                "arn:aws:s3:::amzn-s3-demo-bucket-2"
            ]
        },
        {
            "Action": [
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket-1/*",
                "arn:aws:s3:::amzn-s3-demo-bucket-2/*"
            ]
        }
    ]
}
```

Replace `amzn-s3-demo-bucket-1` and `amzn-s3-demo-bucket-2` with the names of the Amazon S3 buckets you want to grant access to.

### Step 2: Assign the policy in Amazon Quick
<a name="s3-assign-iam-policy"></a>

After creating the IAM policy, assign it to Amazon Quick users or groups.

1. In the Amazon Quick admin console, under **Permissions**, choose **IAM policy assignments**.

1. Choose **Add new assignment**.

1. Enter a name for the assignment.

1. On the **Select an IAM policy** page, search for and select the IAM policy you created in Step 1. Choose **Next**.

1. On the **Assign users and groups** page, choose one of the following:
   + Select **Assign to all users and groups** to apply the policy to all current and future users.
   + Search for and select specific users or groups to assign the policy to.

   Choose **Next**.

1. On the **Review and enable changes** page, verify your assignment details and choose **Save and enable**.

Users who are not explicitly granted access through an IAM policy assignment will not be able to access the restricted Amazon S3 buckets for creating integrations or knowledge bases.

# Document-level ACLs
<a name="s3-acl"></a>

You can enable access control lists (ACLs) at the Amazon S3 knowledge base level using one of two configuration methods, each optimized for different use cases.

**Important**  
Document-level ACL configuration is permanent. You cannot enable ACLs on knowledge bases created without ACL support, and you cannot disable ACLs once enabled. To change ACL configuration, create a new knowledge base with your desired setting from the start.

**Note**  
For ACL-enabled knowledge bases, documents without an associated ACL entry are not ingested. Make sure every document has an ACL defined either through the global ACL file or in its metadata file.

**Global ACL configuration file**  
Create a single centralized file that defines access permissions at the folder level. This provides a streamlined way to manage permissions across large document hierarchies. This method is ideal for organizations with stable permission structures. Any changes to the global file require reindexing the entire affected prefix, which can take hours for knowledge bases with tens of millions of documents. For the file format, see [Global ACL file structure](#s3-global-acl).

**Document-level metadata files**  
Each document has its own metadata file containing specific access control information. This approach requires you to create and maintain individual metadata files for each document. It enables significantly faster index updates when permissions change because only the affected documents need to be reindexed rather than entire folder structures. For more information about configuring ACLs in metadata files, see [Document metadata](s3-metadata.md).

Choose the method that best fits your operational needs: centralized management with the global ACL file for simpler administration, or document-level metadata files for faster permission updates and more granular control.

Keep your document-level ACLs current by regularly updating the Amazon S3 ACL configuration to match your organization's access requirements. For more information about common best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).

## Global ACL file structure
<a name="s3-global-acl"></a>

The global file provides centralized access control management at the folder level. Each entry in the file maps an Amazon S3 key prefix to a set of ACL entries that apply to all documents under that prefix.

The global ACL json file uses the following structure:

```
[
    {
        "keyPrefix": "s3://BUCKETNAME/prefix1/",
        "aclEntries": [
            {
                "Name": "user1@example.com",
                "Type": "USER",
                "Access": "ALLOW"
            },
            {
                "Name": "group1",
                "Type": "GROUP",
                "Access": "DENY"
            }
        ]
    },
    {
        "keyPrefix": "s3://BUCKETNAME/prefix1/document_1.txt",
        "aclEntries": [
            {
                "Name": "user1@example.com",
                "Type": "USER",
                "Access": "ALLOW"
            },
            {
                "Name": "group1",
                "Type": "GROUP",
                "Access": "DENY"
            }
        ]
    },
    {
        "keyPrefix": "s3://BUCKETNAME/prefix2/",
        "aclEntries": [
            {
                "Name": "user2@example.com",
                "Type": "USER",
                "Access": "ALLOW"
            },
            {
                "Name": "user1@example.com",
                "Type": "USER",
                "Access": "DENY"
            },
            {
                "Name": "group1",
                "Type": "GROUP",
                "Access": "DENY"
            }
        ]
    }
]
```

Each entry in the array contains the following fields:

`keyPrefix`  
The Amazon S3 path prefix that the ACL entries apply to. All documents under this prefix inherit the specified permissions.

`aclEntries`  
An array of access control entries, each containing the following fields:  
+ `Name` – For `USER` type, the email address of the user in Quick. For `GROUP` type, the group name in Quick.
+ `Type` – Either `USER` or `GROUP`.
+ `Access` – Either `ALLOW` or `DENY`.

# Document metadata
<a name="s3-metadata"></a>

You can add metadata to documents in your Amazon S3 bucket to customize chat results and control document-level access. Metadata is additional information about a document, such as its title, creation date, and access permissions.

Amazon Quick supports source attribution with citations. If you specify the `_source_uri` metadata field, the source attribution links in chat results direct users to the configured URL. If you don't specify a `_source_uri`, users can still access source documents through clickable citation links that download the file at query time.

## Document metadata location
<a name="s3-metadata-location"></a>

In Amazon S3, each metadata file can be associated with an indexed document. Your metadata files must be stored in the same Amazon S3 bucket as your indexed files. You can specify a location within the Amazon S3 bucket for your metadata files when configuring your Amazon S3 integration in Amazon Quick.

If you don't specify an Amazon S3 prefix, your metadata files must be stored in the same location as your indexed documents. If you specify an Amazon S3 prefix for your metadata files, they must be in a directory structure parallel to your indexed documents. Amazon Quick looks only in the specified directory for your metadata. If the metadata isn't read, check that the directory location matches the location of your metadata.

The following examples show how the indexed document location maps to the metadata file location. The document's Amazon S3 key is appended to the metadata's Amazon S3 prefix and then suffixed with `.metadata.json` to form the metadata file's Amazon S3 path.

**Note**  
The combined Amazon S3 key, the metadata's Amazon S3 prefix, and the `.metadata.json` suffix must be no more than a total of 1,024 characters. We recommend that your Amazon S3 key is less than 1,000 characters to account for additional characters when combining your key with the prefix and suffix.

**Example 1: No metadata path specified**  

```
Bucket name:
     s3://bucketName
Document path:
     documents
Metadata path:
     none
File mapping
     s3://bucketName/documents/file.txt -> 
        s3://bucketName/documents/file.txt.metadata.json
```

**Example 2: Metadata path specified**  

```
Bucket name:
     s3://bucketName
Document path:
     documents/legal
Metadata path:
     metadata
File mapping
     s3://bucketName/documents/legal/file.txt -> 
        s3://bucketName/metadata/documents/legal/file.txt.metadata.json
```

## Document metadata structure
<a name="s3-metadata-structure"></a>

You define your document metadata itself in a JSON file. The file must be a UTF-8 text file without a BOM marker. The file name of the JSON file must be `<document>.<extension>.metadata.json`. In this example, `document` is the name of the document that the metadata applies to and `extension` is the file extension for the document. The document ID must be unique in `<document>.<extension>.metadata.json`.

The content of the JSON file uses the following template:

```
{
    "DocumentId": "document ID",
    "Attributes": {
        "_authors": ["author of the document"],
        "_category": "document category",
        "_created_at": "ISO 8601 encoded string",
        "_last_updated_at": "ISO 8601 encoded string",
        "_source_uri": "document URI",
        "_version": "file version",
        "_view_count": number of times document has been viewed
    },
    "AccessControlList": [
        {
            "Name": "user1@example.com",
            "Type": "GROUP | USER",
            "Access": "ALLOW | DENY"
        }
    ],
    "Title": "document title",
    "ContentType": "PDF | HTML | MS_WORD | PLAIN_TEXT | PPT | RTF | XML | XSLT | MS_EXCEL | CSV | JSON | MD"
}
```

If you provide a metadata path, make sure that directory structure inside the metadata directory exactly matches the directory structure of data file.

For example, if the data file location is at `s3://bucketName/documents/legal/file.txt`, the metadata file location should be at `s3://bucketName/metadata/documents/legal/file.txt.metadata.json`.

All of the attributes and fields are optional, so it's not necessary to include all attributes. However, you must provide a value for each attribute that you want to include; the value can't be empty.

The `_created_at` and `_last_updated_at` metadata fields are ISO 8601 encoded dates. For example, 2012-03-25T12:30:10\$101:00 is the ISO 8601 date-time format for March 25, 2012, at 12:30PM (plus 10 seconds) in the Central European Time time zone.

The `AccessControlList` field is an optional array that defines document-level access control. Each entry in the array contains the following fields:
+ `Name` – For `USER` type, the email address of the user in Quick. For `GROUP` type, the group name in Quick.
+ `Type` – Either `USER` or `GROUP`.
+ `Access` – Either `ALLOW` or `DENY`.

**Note**  
To use the `AccessControlList` field, you must enable document-level ACLs when creating the knowledge base. For more information, see [Document-level ACLs](s3-acl.md).

# Set up and manage Amazon S3 integration
<a name="s3-setup-manage"></a>

## Set up Amazon S3 integration
<a name="s3-integration-setup"></a>

After your administrator has completed the setup tasks, follow these steps to create your Amazon S3 knowledge base.

1. In the Amazon Quick console, choose **Integrations**.

1. Under **Amazon S3**, choose **Add** (the plus **\$1** button).

1. On the **Connect S3 bucket** page, choose your data source:
   + To reuse an existing Amazon S3 data source, select it from the dropdown. Then choose **Next** to skip to the knowledge base details step.
   + To connect a new Amazon S3 bucket, choose **\$1 Add account** from the dropdown.

1. If you are connecting a new bucket, fill in the connection details:
   + **Name** – A descriptive name for your Amazon S3 integration.
   + **S3 bucket location** – Choose **Quick Suite instance account** to access Amazon S3 buckets in the same Amazon account where Amazon Quick is enabled, or choose **Other Amazon account** to access buckets in a different account.
   + **S3 bucket URL** – The Amazon S3 bucket path containing your documents. Your Amazon S3 bucket must be in the same region as your Amazon Quick region.

   Choose **Next**. The system validates your configuration. If errors occur, review the error message for specific remediation steps.
**Note**  
If you receive an access error, contact your administrator to verify that your user has the required permissions for the Amazon S3 bucket.

1. On the **Create knowledge base** page, complete the following:
   + **Name** – Enter a descriptive name for your knowledge base.
   + **Description** – Describe the purpose of this knowledge base (optional).
   + **Content** – Choose **Add all content** to sync everything from the bucket, or choose **Add specific content** to specify S3 prefixes for the folders and files you want to include. Filters are case-sensitive.

1. Choose **Next: Additional settings** to configure ACL and metadata options, or choose **Create** to create the knowledge base with default settings.

1. On the **Additional settings** page, configure ACL management and metadata:
**Important**  
The decision to enable or disable ACLs must be made during knowledge base creation. You cannot change this option after this step. For more information about ACLs, see [Document-level ACLs](s3-acl.md).
   + To enable document-level ACLs, select **Control document access with ACLs**. When enabled, the following options appear:
     + **Global ACL file location** – Enter the Amazon S3 path to your global ACL file (e.g. acl.json) if you are using a global ACL configuration file for centralized access control management at the folder level.
     + **Metadata files folder location** – Enter the Amazon S3 path to your metadata folder if you are using document-level metadata files that include ACL entries.
     + If your metadata files use the sidecar method (stored in the same folder as the original documents), you can leave both fields blank.
   + You can optionally specify a **Metadata files folder location** even without ACLs enabled.

1. Choose **Create**.

After you choose create, the data sync starts automatically.

## Manage knowledge bases
<a name="s3-integration-knowledge-base"></a>

After setting up your Amazon S3 integration, you can create and manage knowledge bases from your Amazon S3 content.

### Edit existing knowledge bases
<a name="s3-edit-knowledge-base"></a>

You can modify your existing Amazon S3 knowledge bases:

1. In the Amazon Quick console, choose **Knowledge bases**.

1. Select your Amazon S3 knowledge base from the list.

1. Choose the three-dot icon under **Actions**, then choose **Edit knowledge base**.

1. Update your configuration settings as needed and choose **Save**.

### Create additional knowledge bases
<a name="s3-create-additional-knowledge-base"></a>

You can create multiple knowledge bases from the same Amazon S3 integration:

1. In the Amazon Quick console, choose **Integrations**, and then select the **Data** tab.

1. Choose your existing Amazon S3 integration from the list.

1. Choose the three-dot icon under **Actions**, then choose **Create knowledge base**.

1. Configure your knowledge base settings and choose **Create**.

For detailed information about knowledge base configuration options, see [Common configuration settings](knowledge-base-integrations.md#common-configuration-settings).

**Note**  
When you create a knowledge base in Amazon Quick, by default only you can get insights from the knowledge base. For shared content, you can provide access to different users and groups by updating the knowledge base permissions. To control document-level access within a knowledge base, see [Document-level ACLs](s3-acl.md).

# Troubleshooting Amazon S3 integration issues
<a name="s3-integration-troubleshooting"></a>

If you encounter issues connecting to your Amazon S3 bucket, review the following common causes and solutions.

## Documents not appearing in ACL-enabled knowledge base
<a name="s3-troubleshooting-acl-documents-missing"></a>

**Issue:** Documents are not ingested into an ACL-enabled knowledge base.

**Solution:** For ACL-enabled knowledge bases, documents without an associated ACL entry are not ingested. Verify that every document has an ACL defined either through the global ACL file or in its metadata file. For more information, see [Document-level ACLs](s3-acl.md).

## Cross-account access not configured
<a name="s3-troubleshooting-cross-account"></a>

**Issue:** Your administrator hasn't granted access to use Amazon S3 buckets from other Amazon accounts in Amazon Quick.

**Solution:** Ask your administrator to grant cross-account Amazon S3 access. For more information, see [Grant Amazon Quick access to Amazon S3 buckets](s3-admin-setup.md#s3-grant-bucket-access).

## Bucket not in approved list
<a name="s3-troubleshooting-bucket-not-approved"></a>

**Issue:** The bucket you're trying to access hasn't been authorized by your administrator.

**Solution:**
+ Confirm the bucket name is spelled correctly.
+ Verify with your administrator that the bucket is included in the approved list.
+ Request your administrator to add the bucket to the authorized buckets list if needed.

## Insufficient IAM permissions
<a name="s3-troubleshooting-iam-permissions"></a>

**Issue:** Your IAM role or user lacks the necessary permissions to access the Amazon S3 bucket.

**Solution:**
+ Verify your IAM policy includes the required Amazon S3 permissions:
  + `s3:GetObject`
  + `s3:ListBucket`
  + `s3:GetBucketLocation`
  + `s3:GetObjectVersion`
  + `s3:ListBucketVersions`
+ Check your own buckets for any explicit Deny statements that might be blocking access.

**Note**  
The ARN `arn:aws:iam::account-id:role/service-role/aws-quicksight-service-role-v0` is the default service role used when no custom role has been created. If a custom service role exists, contact your administrator to obtain the custom service role ARN and use it instead of the default.

## Cross-region restrictions
<a name="s3-troubleshooting-cross-region"></a>

**Issue:** The Amazon S3 bucket is located in a different Amazon region than your Amazon Quick account or service.

**Solution:**
+ Verify the bucket region matches your Amazon Quick service region.
+ Check bucket region using Amazon CLI: `aws s3api get-bucket-location --bucket bucket-name`
+ Use a bucket in the same region as your service.

## Additional troubleshooting steps
<a name="s3-troubleshooting-additional-steps"></a>
+ **Test bucket accessibility** using Amazon CLI:

  ```
  aws s3 ls s3://bucket-name --profile your-profile
  ```
+ **Review CloudTrail logs** for AccessDenied errors to identify the specific permission issue.
+ **Check Amazon S3 Block Public Access settings** - while these typically don't affect authenticated access, verify they're not interfering with your specific use case.
+ **Verify bucket ownership** - ensure the bucket exists and you have the correct bucket name.

# Limitations
<a name="s3-limitations"></a>

When using Amazon S3 integrations in Amazon Quick, be aware of the following limitations:
+ The Amazon S3 bucket must be in the same Amazon Region as your Amazon Quick application.
+ Each document can have a maximum of 2,500 individual user or group ACL entries.
+ Global ACL configuration file maximum size: 100 MB.
+ Document metadata file maximum size: 5 MB.

For more information about document-level ACL limitations, see [Limitations](acl-best-practices-kb.md#acl-limitations).