Common errors from the Amazon QLDB driver

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.

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.

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.

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 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.

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.

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.

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.