Troubleshooting Amazon QLDB

The following sections provide an aggregate list of common errors that you might encounter when using Amazon QLDB, and guidance for how to troubleshoot them.

For troubleshooting guidance specific to IAM access, see Troubleshooting Amazon QLDB identity and access.

For best practices for tuning your PartiQL statements, see Optimizing query performance.

Running transactions using the QLDB driver

This section lists common exceptions that the Amazon QLDB driver can return when you use it to run PartiQL transactions on a ledger. For more information about this feature, see Getting started with the driver. For best practices for configuring and using the driver, see Driver recommendations.

Each exception includes the specific error message, followed by a short description and suggestions for possible solutions.

CapacityExceededException

Message: Capacity exceeded

Amazon QLDB rejected the request because it exceeded the processing capacity of the ledger. QLDB enforces an internal scaling limit per ledger to maintain the health and performance of the service. This limit varies depending on the workload size of each individual request. For example, a request can have an increased workload if it performs inefficient data transactions, such as table scans that result from a non-index qualified query.

We recommend that you wait before retrying the request. If your application consistently encounters this exception, optimize your statements and decrease the rate and volume of the requests that you send to the ledger. Examples of statement optimization include running fewer statements per transaction and tuning your table indexes. To learn how to optimize statements and avoid table scans, see Optimizing query performance.

We also recommend using the latest version of the QLDB driver. The driver has a default retry policy that uses Exponential Backoff and Jitter to automatically retry on exceptions such as this. The concept of exponential backoff is to use progressively longer wait times between retries for consecutive error responses.

InvalidSessionException

Message: Transaction transactionId has expired

A transaction exceeded its maximum lifetime. A transaction can run for up to 30 seconds before being committed. After this timeout limit, any work done on the transaction is rejected, and QLDB discards the session. This limit protects the client from leaking sessions by starting transactions and not committing or canceling them.

If this is a common exception in your application, it's likely that transactions are simply taking too long to run. If transaction runtime is taking longer than 30 seconds, optimize your statements to speed up the transactions. Examples of statement optimization include running fewer statements per transaction and tuning your table indexes. For more information, see Optimizing query performance.

InvalidSessionException

Message: Session sessionId has expired

QLDB discarded the session because it exceeded its maximum total lifetime. QLDB discards sessions after 13–17 minutes, regardless of an active transaction. Sessions can be lost or impaired for a number of reasons, such as hardware failure, network failure, or application restarts. So, QLDB enforces a maximum lifetime on sessions to ensure that client software is resilient to session failure.

If you encounter this exception, we recommend that you acquire a new session and retry the transaction. We also recommend using the latest version of the QLDB driver, which manages the session pool and its health on the application's behalf.

InvalidSessionException

Message: No such session

The client tried to transact with QLDB using a session that doesn't exist. Assuming that the client is using a session that previously existed, the session might no longer exist because of one of the following:

• If a session is involved in an internal server failure (that is, an error with HTTP response code 500), QLDB might choose to discard the session completely, rather than allow the customer to transact with a session of uncertain state. Then, any retry attempts on that session fail with this error.

• Expired sessions are eventually forgotten by QLDB. Then, any attempts to continue using the session result in this error, rather than the initial InvalidSessionException.

If you encounter this exception, we recommend that you acquire a new session and retry the transaction. We also recommend using the latest version of the QLDB driver, which manages the session pool and its health on the application's behalf.

RateExceededException

Message: The rate was exceeded

QLDB throttled a client based on the caller's identity. QLDB enforces throttling on a per-Region, per-account basis using a token bucket throttling algorithm. QLDB does this to help the performance of the service, and to ensure fair usage for all QLDB customers. For example, trying to acquire a large number of concurrent sessions using the StartSessionRequest operation might lead to throttling.

To maintain your application health and mitigate further throttling, you can retry on this exception using Exponential Backoff and Jitter. The concept of exponential backoff is to use progressively longer wait times between retries for consecutive error responses. We recommend using the latest version of the QLDB driver. The driver has a default retry policy that uses exponential backoff and jitter to automatically retry on exceptions such as this.

The latest version of the QLDB driver can also help if your application is consistently getting throttled by QLDB for StartSessionRequest calls. The driver maintains a pool of sessions that are reused across transactions, which can help to reduce the number of StartSessionRequest calls that your application makes. To request an increase in API throttling limits, contact the AWS Support Center.

LimitExceededException

Message: Exceeded the session limit

A ledger exceeded its quota (also known as a limit) on the number of active sessions. This quota is defined in Quotas and limits in Amazon QLDB. A ledger's active session count is eventually consistent, and ledgers consistently running near the quota might periodically see this exception.

To maintain your application's health, we recommend retrying on this exception. To avoid this exception, ensure that you have not configured more than 1,500 concurrent sessions to be used for a single ledger across all clients. For example, you can use the maxConcurrentTransactions method of the Amazon QLDB driver for Java to configure the maximum number of available sessions in a driver instance.

QldbClientException

Message: A streamed result is only valid when the parent transaction is open

The transaction is closed, and it can't be used to retrieve the results from QLDB. A transaction closes when it's either committed or canceled.

This exception occurs when the client is working directly with the Transaction object, and it's trying to retrieve results from QLDB after committing or canceling a transaction. To mitigate this issue, the client must read the data before closing the transaction.

Exporting journal data

This section lists common exceptions that QLDB can return when you export journal data from a ledger into an Amazon S3 bucket. For more information about this feature, see Exporting journal data from Amazon QLDB.

Each exception includes the specific error message, followed by a short description and suggestions for possible solutions.

AccessDeniedException

Message: User: userARN is not authorized to perform: iam:PassRole on resource: roleARN

You don't have permissions to pass an IAM role to the QLDB service. QLDB requires a role for all journal export requests, and you must have permissions to pass this role to QLDB. The role provides QLDB with write permissions in your specified Amazon S3 bucket.

Verify that you define an IAM policy that grants permission to perform the PassRole API operation on your specified IAM role resource for the QLDB service (qldb.amazonaws.com). For a policy example, see Identity-based policy examples for Amazon QLDB.

IllegalArgumentException

Message: QLDB encountered an error validating S3 configuration: errorCode errorMessage

A possible cause for this error is that the provided Amazon S3 bucket doesn't exist in Amazon S3. Or, QLDB doesn't have enough permissions to write objects into your specified Amazon S3 bucket.

Verify that the S3 bucket name that you provide in your export job request is correct. For more information about bucket naming, see Bucket restrictions and limitations in the Amazon Simple Storage Service User Guide.

Also, verify that you define a policy for your specified bucket that grants PutObject and PutObjectAcl permissions to the QLDB service (qldb.amazonaws.com). To learn more, see Export permissions.

IllegalArgumentException

Message: Unexpected response from Amazon S3 while validating the S3 configuration. Response from S3: errorCode errorMessage

The attempt to write journal export data into the provided S3 bucket failed with the provided Amazon S3 error response. For more information about possible causes, see Troubleshooting Amazon S3 in the Amazon Simple Storage Service User Guide.

IllegalArgumentException

Message: Amazon S3 bucket prefix must not exceed 128 characters

The prefix provided in the journal export request contains more than 128 characters.

IllegalArgumentException

Message: Start date must not be greater than end date

Both InclusiveStartTime and ExclusiveEndTime must be in ISO 8601 date and time format and in Coordinated Universal Time (UTC).

IllegalArgumentException

Message: End date cannot be in the future

Both InclusiveStartTime and ExclusiveEndTime must be in ISO 8601 date and time format and in UTC.

IllegalArgumentException

Message: The supplied object encryption setting (S3EncryptionConfiguration) is not compatible with an AWS Key Management Service (AWS KMS) key

You provided a KMSKeyArn with an ObjectEncryptionType of either NO_ENCRYPTION or SSE_S3. You can only provide a customer managed AWS KMS key for an object encryption type of SSE_KMS. To learn more about server-side encryption options in Amazon S3, see Protecting data using server-side encryption in the Amazon S3 Developer Guide.

LimitExceededException

Message: Exceeded the limit of 2 concurrently running Journal export jobs

QLDB enforces a default limit of two concurrent journal export jobs.

Streaming journal data

This section lists common exceptions that QLDB can return when you stream journal data from a ledger to Amazon Kinesis Data Streams. For more information about this feature, see Streaming journal data from Amazon QLDB.

Each exception includes the specific error message, followed by a short description and suggestions for possible solutions.

AccessDeniedException

Message: User: userARN is not authorized to perform: iam:PassRole on resource: roleARN

You don't have permissions to pass an IAM role to the QLDB service. QLDB requires a role for all journal stream requests, and you must have permissions to pass this role to QLDB. The role provides QLDB with write permissions in your specified Amazon Kinesis Data Streams resource.

Verify that you define an IAM policy that grants permission to perform the PassRole API operation on your specified IAM role resource for the QLDB service (qldb.amazonaws.com). For a policy example, see Identity-based policy examples for Amazon QLDB.

IllegalArgumentException

Message: QLDB encountered an error validating Kinesis Data Streams: Response from Kinesis: errorCode errorMessage

A possible cause for this error is that the provided Kinesis Data Streams resource doesn't exist. Or, QLDB doesn't have enough permissions to write data records to your specified Kinesis data stream.

Verify that the Kinesis data stream that you provide in your stream request is correct. For more information, see Creating and updating data streams in the Amazon Kinesis Data Streams Developer Guide.

Also, verify that you define a policy for your specified Kinesis data stream that grants the QLDB service (qldb.amazonaws.com) permissions to the following actions. For more information, see Stream permissions.

• kinesis:PutRecord

• kinesis:PutRecords

• kinesis:DescribeStream

• kinesis:ListShards

IllegalArgumentException

Message: Unexpected response from Kinesis Data Streams while validating the Kinesis configuration. Response from Kinesis: errorCode errorMessage

The attempt to write data records to the provided Kinesis data stream failed with the provided Kinesis error response. For more information about possible causes, see Troubleshooting Amazon Kinesis Data Streams producers in the Amazon Kinesis Data Streams Developer Guide.

IllegalArgumentException

Message: Start date must not be greater than end date.

Both InclusiveStartTime and ExclusiveEndTime must be in ISO 8601 date and time format and in Coordinated Universal Time (UTC).

IllegalArgumentException

Message: Start date cannot be in the future.

Both InclusiveStartTime and ExclusiveEndTime must be in ISO 8601 date and time format and in UTC.

LimitExceededException

Message: Exceeded the limit of 5 concurrently running Journal streams to Kinesis Data Streams

QLDB enforces a default limit of five concurrent journal streams.

Verifying journal data

This section lists common exceptions that QLDB can return when you verify journal data in a ledger. For more information about this feature, see Data verification in Amazon QLDB.

Each exception includes the specific error message, followed by the API operations that can throw it, a short description, and suggestions for possible solutions.

IllegalArgumentException

Message: The provided Ion value is not valid and cannot be parsed.

API operations: GetDigest, GetBlock, GetRevision

Make sure that you provide a valid Amazon Ion value before retrying your request.

IllegalArgumentException

Message: The provided block address is not valid.

API operations: GetDigest, GetBlock, GetRevision

Make sure that you provide a valid block address before retrying your request. A block address is an Amazon Ion structure that has two fields: strandId and sequenceNo.

For example: {strandId:"BlFTjlSXze9BIh1KOszcE3",sequenceNo:14}

IllegalArgumentException

Message: The sequence number of the provided digest tip address is beyond the strand's latest committed record.

API operations: GetDigest, GetBlock, GetRevision

The digest tip address that you provide must have a sequence number less than or equal to the sequence number of the journal strand's latest committed record. Before retrying your request, make sure that you provide a digest tip address with a valid sequence number.

IllegalArgumentException

Message: The Strand ID of the provided block address is not valid.

API operations: GetDigest, GetBlock, GetRevision

The block address that you provide must have a strand ID that matches the journal's strand ID. Before retrying your request, make sure that you provide a block address with a valid strand ID.

IllegalArgumentException

Message: The sequence number of the provided block address is beyond the strand's latest committed record.

API operations: GetBlock, GetRevision

The block address that you provide must have a sequence number less than or equal to the sequence number of the strand's latest committed record. Before retrying your request, make sure that you provide a block address with a valid sequence number.

IllegalArgumentException

Message: The Strand ID of the provided block address must match the Strand ID of the provided digest tip address.

API operations: GetBlock, GetRevision

You can only verify a document revision or block if it exists in the same journal strand as the digest that you provide.

IllegalArgumentException

Message: The sequence number of the provided block address must not be greater than the sequence number of the provided digest tip address.

API operations: GetBlock, GetRevision

You can only verify a document revision or block if it's covered by the digest that you provide. This means that it was committed to the journal before the digest tip address.

IllegalArgumentException

Message: The provided Document ID was not found in the block at the specified block address.

API operation: GetRevision

The document ID that you provide must exist in the block address that you provide. Before retrying your request, make sure that these two parameters are consistent.