failOnError

Uses

Normally, if you run the update command and Liquibase detects an error in a changeset, the migration fails. However, if you set failOnError to false on a changeset, Liquibase suppresses all error caching for that changeset, so the migration continues as though there were no error.

Some databases contain complex logic or objects added outside of Liquibase that may cause certain changesets to fail. To ensure your migrations succeed, it is a best practice to write one or more preconditions that control the execution of these changesets. However, if the precondition(s) would be very complicated to write, it may be more convenient to set failOnError to false on the affected changesets.

If you have a changeset that only runs successfully with certain databases or environments, it is also possible to set failOnError on it as a "quick fix" to control its execution. However, instead of relying on failOnError, it is a best practice to use the dbms attribute to control whether a changeset applies to different databases. Similarly, it is a best practice to use contexts or labels to control changeset execution across multiple environments, such as test versus dev. failOnError: false is honored when a custom change class cannot be found on the classpath, allowing the migration to continue rather than failing the entire changelog. This is useful when custom changes are optional or environment-specific, such as a data transformation that applies to a live database but can be safely skipped when setting up an empty test database.

Note:As of Liquibase Secure 5.1 and Liquibase Community 5.0.2, failOnError: false is honored when a custom change class cannot be found on the classpath, allowing the migration to continue rather than failing the entire changelog. This is useful when custom changes are optional or environment-specific, such as a data transformation that applies to a live database but can be safely skipped when setting up an empty test database.

If you use failOnError frequently, consider whether there are any underlying issues with your database architecture that you can address instead.

Using failOnError with --rollback-on-error (Liquibase Secure)

You can use the failOnError changeset attribute with the update command argument --rollback-on-error. The following table displays the outcomes of running update on a changeset that contains an error based on each possible configuration.

Note: --rollback-on-error requires Liquibase Secure.

* If you use --rollback-on-error=true, by default Liquibase does not roll back partially deployed changesets, such as a changeset containing one change with an error and one change without an error.