Troubleshooting data source connectors - Amazon Q Business
My documents were not indexedMy synchronization job failedMy synchronization job is incompleteMy synchronization job succeeded but there are no indexed documentsI am running into file format issues while syncing my data sourceI am getting an AccessDenied When Using SSL Certificate File error message

Troubleshooting data source connectors

This section can help you fix issues with Amazon Q Business data source connectors.

My documents were not indexed

When you synchronize your Amazon Q Business index with a data source, you may run into issues that prevent the documents from being indexed. Indexing is a two-step process. First, the data source is checked for new and updated documents to index, and to find documents to remove from the index. Second, at the document level, each document is accessed and indexed.

An error can occur in either of these steps. Data source level errors are reported in the console in the Sync run history section of the data source details page. The status of the synchronization job can be Succeeded, Incomplete, or Failed. You can also see the number of documents indexed and deleted during the job. If the status is Failed, a message is shown in the Details column.

Document level errors are reported in Amazon CloudWatch Logs. You can see the errors using the CloudWatch console.

You can view a document-level sync run history report in CloudWatch for your data source sync job by selecting View Report. A sync run history report will have details about the progress and status of each document in the sync job. It shows if a document succeeded, failed, or was skipped during the crawl, sync, and index stages. You'll also find any error messages related to failed or skipped documents. If the report doesn't show results for an in-progress sync job, the logs may not be available yet. Check back later as data is emitted to the report as events occur during the sync process.

To access your sync run history report, take the following steps:

  1. Open the Amazon Q Business console.

  2. From the left navigation menu, under Enhancements, choose Data sources, and then choose your data source.

  3. From your data source summary page, scroll down and select the Sync history tab.

  4. From Sync run history, select Actions.

  5. From Actions, select View report. You will be redirected to the CloudWatch console where you will be able to access your report.

A sync run history records if a document was successfully indexed during ingestion, including attached ACLs and metadata, for all Amazon Q Business supported connectors.

Note

To learn more about generating and understanding a sync run history report, see Introducing document-level sync reports: Enhanced data sync visibility in Amazon Q Business in the AWS Machine Learning Blog. To learn more about analyzing data using Amazon CloudWatch, see Analyzing log data with CloudWatch Logs Insights in the Amazon CloudWatch User Guide.

My synchronization job failed

A synchronization job typically fails when there is a configuration error in the index or the data source. In the console, you can find the error message in the Sync run history section of the data source details page, under the Details column. Document level errors are reported in Amazon CloudWatch Logs. The error message gives information about what went wrong. The problem is usually that the index or the data source doesn't have the correct IAM permissions. The error message describes the missing permissions. Following are some of the error messages that you can receive:

Failed to create log group for job. Please make sure that the IAM role provided has sufficient permissions.

If your index role doesn't have permissions to use CloudWatch, the data source can't create a CloudWatch log. If you get this error, you must add CloudWatch permissions to the index role.

Failed to access Amazon S3 file prefix (bucket name) while trying to crawl your metadata files. Please make sure the IAM role (ARN) provided has sufficient permissions.

When you're using an Amazon S3 data source, Amazon Q Business must have permissions to access the bucket that contains the documents. You need to add permissions for Amazon Q Business to read the bucket to the data source IAM role.

The provided IAM role (ARN) could not be assumed. Please make sure Amazon Q Business is a trusted entity that is allowed to assume the role.

Amazon Q Business needs permissions to assume the index and data source IAM roles. You need to add a trust policy to the roles with permissions for the sts:AssumeRole action.

For the IAM policies that Amazon Q Business needs to index a data source, see IAM roles for Amazon Q Business connectors.

My synchronization job is incomplete

Jobs are generally incomplete when they have completed the data source level process but have some error during the document level process. When a job is incomplete, some of the documents might not have indexed successfully . For an Amazon S3 data source, an incomplete job is typically caused by one of the following issues:

  • The metadata for one or more documents was not valid.

  • When documents are submitted for indexing but at least one document was not submitted.

  • When documents are submitted for deleting from the index but at least one document was not submitted.

To troubleshoot an incomplete synchronization job, look first to your CloudWatch logs.

  1. From the details column, choose View details in CloudWatch.

  2. Review the error messages to see what caused the document to fail.

My synchronization job succeeded but there are no indexed documents

Occasionally, an index synchronization job run is marked as Succeeded, but there are no new or updated documents indexed when you expect them. Possible reasons include the following:

  • Check CloudWatch DocumentsSubmittedForIndexingFailed metric to see if any documents failed to synchronize. Check your CloudWatch logs for details.

  • For an Amazon S3 data source, you might have given Amazon Q Business the wrong bucket name or prefix. Make sure that the S3 bucket that Amazon Q Business is using is the bucket that contains the documents to index.

  • When re-indexing a document that failed to be indexed in an earlier job, Amazon Q Business won't index it unless you've changed the document or its associated metadata file.

I am running into file format issues while syncing my data source

If you run into file format issues while adding files to your data source or syncing your data source, make sure that your document types are supported by Amazon Q Business. For a list of document types supported by Amazon Q see Supported document types.

If you're using the BatchPutDocument API operation with plaintext files, specify PLAIN_TEXT as the content type.

I am getting an AccessDenied When Using SSL Certificate File error message

If you're getting an access denied error when using an SSL certificate with your data source, make sure that your IAM role has the permissions to access the SSL certificate file in its specified location. If the certificate is encrypted with an AWS KMS key, your IAM role should also have permissions to decrypt using the AWS KMS key. For more information, see Authentication and access control for AWS KMS in the AWS Key Management Service Developer Guide.