Common Errors from the Amazon QLDB Driver - Amazon Quantum Ledger Database (Amazon QLDB)

Common Errors from the Amazon QLDB Driver

This section describes runtime errors that can be thrown by the Amazon QLDB Driver when calling the QLDB Session API.

The following is a list of common exceptions that are returned by the driver. Each exception includes the specific error message, followed by a short description and suggestions for possible solutions.

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 limit, any work done on the transaction is rejected, and Amazon QLDB discards the session. This limit protects the client from leaking sessions by starting transactions and not committing or aborting them.

If this is a common exception in your application, it is likely that transactions are simply taking too long to execute. If transaction execution is taking longer than 30 seconds, optimize your statements to speed up the transactions. Examples of statement optimization include executing fewer statements per transaction and tuning your table indexes.

InvalidSessionException

Message: Exceeded the session idle time limit: Session sessionId

QLDB has discarded the session because it remained idle past the idle time limit. QLDB defines an idle session as a session that is not in an active transaction. A session can be idle for up to 60 seconds, after which QLDB discards the session to protect the client from leaking sessions.

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 QldbDriver object and its execute method. This driver manages the session pool and its health on the application's behalf.

InvalidSessionException

Message: Session sessionId has expired

QLDB discarded the session because it exceeded its maximum total lifetime. QLDB discards sessions after approximately 15 minutes, regardless of idleness. 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 QldbDriver object and its execute method. This driver object 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.

  • Sessions that expire or exceed the idle time limit 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 QldbDriver object and its execute method. This driver object 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. If your application is consistently getting throttled by QLDB for StartSessionRequest calls, we recommend using the latest version of the QldbDriver. This driver object 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 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 aborted.

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 aborting a transaction. To mitigate this issue, the client should read the data before closing the transaction.