• Reference
  • Version · 6.0
  • Change Automation Reference

dynamodb-waiter-update-max-attempts

Last updated: August 12, 2026

--dynamodb-waiter-update-max-attempts is a global parameter for the Liquibase DynamoDB Secure extension. It specifies the maximum number of polling attempts for the DynamoDbWaiter to make. The waiter repeatedly polls your table to see if it is updated and operable. When the waiter exceeds this number of attempts, it enters a failure state. The default value is 25.

Uses

When you ask Amazon DynamoDB to run an operation on a resource in your database, such as creating, updating, or deleting a table, DynamoDB calls a waiter class first. Waiters are AWS SDK objects that ensure consistency in distributed systems when DynamoDB doesn't perform operations instantly, but some code needs to wait until those operations are fully completed.

The waiter repeatedly checks whether the table is in the correct state (it "polls" the table). If the table is in the correct state (ACTIVE or non-existent), the waiter approves the operation. Otherwise, if the table status is CREATING, UPDATING, or DELETING, it tries polling again. The waiter repeats this indefinitely or until it times out. For more information, see Poll for resource states in the AWS SDK for Java 2.x: Waiters.

Note: Liquibase does not use Amazon DynamoDB waiters when you create, update, or delete indexes.

When you run Liquibase commands like update and rollback, Liquibase runs your changesets sequentially. For every change, it waits a default amount of time for DynamoDB to respond before moving onto the next changeset. The default waiter settings are appropriate for most situations. However, some operations may require custom waiter values to avoid errors or keep your CI/CD pipeline efficient.

You can customize the following behavior with Liquibase waiter parameters:

  • Enabled: whether the waiter makes any polling attempts

  • Interval: how long to wait between polling attempts

  • Attempts: how many times to attempt to poll the resource

  • Timeout: the total amount of time to spend polling

  • Exit code: whether Liquibase fails after a waiter timeout

  • Logs: whether Liquibase tells you about the status of the waiter, and how often to do so

The --dynamodb-waiter-update-max-attempts parameter controls the number of polling attempts the waiter makes before timing out:

  • If you want to use a short interval between polling attempts, set a higher value (more attempts). This may help latency-sensitive applications operate efficiently without prematurely timing out.

  • If you want make fewer unnecessary server requests, set a lower value (fewer attempts). This may help you avoid spending too long polling resources that are in a perpetually invalid state.

Syntax

You can set this parameter in the following ways:

Option

Syntax

Liquibase properties file (defaults file)

liquibase.dynamodb.waiter.update.maxAttempts: <int>

Global flow file argument (example)

stages: Default: actions: - type: liquibase command: update globalArgs: { dynamodb-waiter-update-maxattempts: "<int>" }

Global CLI parameter

liquibase --dynamodb-waiter-update-max-attempts= <int>update

--changelog-file=example-changelog.xml

JVM system property (JAVA_OPTS Environment Variable)

Unix:

JAVA_OPTS=Dliquibase.dynamodb.waiter.update.maxAttempts=<int>

Windows:

JAVA_OPTS=D"liquibase.dynamodb.waiter.update.maxAttempts"=<int>

Liquibase Environment Variables

LIQUIBASE_DYNAMODB_WAITER_UPDATE_MAX_ATTEMPTS=<int>

For more information, see Working with Command Parameters.

Troubleshooting

If you reach the maximum number of retries and the --dynamodb-waiters-fail-on-timeout parameter is set to true, Liquibase returns an exit code of 1 and displays the following message:

Unexpected error running Liquibase: Migration failed for changeset changelogs/updateTable.xml::2::your.name: Reason: liquibase.exception.DatabaseException: Could not execute - Caused by: The waiter has exceeded the max retry attempts: 25

To fix this issue, try one or both of the following strategies:

  • Increase the number of retry attempts by specifying a higher value for --dynamodb-waiter-update-max-attempts.

  • Increase the interval between retries by specifying a higher value for --dynamodb-waiter-update-fixed-delay-backoff-strategy-duration.

PreviousDynamodb-waiter-update-fixed-delay-backoff-strategy-durationNextDynamodb-waiter-update-total-timeout