failOnError

The failOnError attribute defines whether a database migration will fail if an error occurs while executing the changeset. The default value is true.

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.

Tip: 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 Pro)

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.

failOnError value --rollback-on-error value Migration state Rollback behavior
true true Fails All changes in the migration are rolled back *
true false No rollback
false true Continues
false false

Note: --rollback-on-error requires a Liquibase Pro license key to use. For more information, see How to Apply Your Liquibase Pro License Key.

* 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. In Liquibase Pro 4.25.0 and later, you can use the update argument --force-on-partial-changes=true alongside --rollback-on-error=true to roll back these partially deployed changesets containing errors.

Syntax

Note: All changelog attributes use the camelCase format.

--changeset adrian:1 failOnError:false
create table company (
    id int primary key,
    address varchar(255)
);
<changeSet  id="1"  author="adrian"  failOnError="false">
    <createTable  tableName="company">
        <column  name="address"  type="varchar(255)"/>
    </createTable>
</changeSet>
databaseChangeLog:
  -  changeSet:  
      id:  1
      author:  adrian
      failOnError:  false
      changes:
        -  createTable:
            tableName:  company
            columns:
              -  column:
                  name:  address
{
  "changeSet": {
    "id": "1",
    "author": "adrian",
    "failOnError": "false",
    "changes": [
      {
        "createTable": {
          "tableName": "company",
          "columns": [
            {
              "column": {
                "name": "address"
              }
            }
          ]
        }
      }
    ]
  }
}

Related links