Troubleshooting Amazon QLDB
Important
End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see
Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL
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.
Topics
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 expiredA 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 expiredQLDB 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 ofStartSessionRequest
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
andPutObjectAcl
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
andExclusiveEndTime
must be in ISO 8601date and time format and in Coordinated Universal Time (UTC). - IllegalArgumentException
-
Message:
End date cannot be in the future
Both
InclusiveStartTime
andExclusiveEndTime
must be inISO 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 anObjectEncryptionType
of eitherNO_ENCRYPTION
orSSE_S3
. You can only provide a customer managed AWS KMS key for an object encryption type ofSSE_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
andExclusiveEndTime
must be in ISO 8601date and time format and in Coordinated Universal Time (UTC). - IllegalArgumentException
-
Message:
Start date cannot be in the future.
Both
InclusiveStartTime
andExclusiveEndTime
must be inISO 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
andsequenceNo
.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.