The global parameter error-on-circular-include-all is a Boolean that specifies whether Liquibase throws an error if it detects that an includeAll will cause a circular reference (and thus a changelog parse error). The default value is true.


You can use the includeAll tag to structure several changelogs in a directory under a root changelog. When error-on-circular-include-all is set to true, Liquibase automatically checks whether the directory you specify for includeAll contains the changelog you are executing, either directly or through another includeAll. This is called a circular or recursive reference and will cause program failure. If any circular references are detected, Liquibase stops the deployment.

It's possible to accidentally introduce a circular reference if you have multiple nested changelogs using includeAll. To help you easily find the cause of a failure, it is a best practice to leave error-on-circular-include-all set to true (the default behavior). However, you can set it to false if necessary.

Warning: If you set error-on-circular-include-all to false and your changelog contains a circular includeAll reference, Liquibase will generate a StackOverflowError and terminate.


You can set this parameter in the following ways:

Option Syntax
Liquibase properties file
liquibase.errorOnCircularIncludeAll: <true|false>
Global flow file argument (example)
      - type: liquibase
        command: update
        globalArgs: { error-on-circular-include-all: "<true|false>" }
Global CLI parameter
 --error-on-circular-include-all=<true|false> update

JVM system property (JAVA_OPTS Environment Variable)

Liquibase Environment Variables

For more information, see Working with Command Parameters.


If you set the parameter to true, Liquibase notifies you that the failure was caused by an infinite loop in your includeAll:

Unexpected error running Liquibase: Circular reference detected in '../xml/'. Set liquibase.errorOnCircularIncludeAll if you'd like to ignore this error.

If you set the parameter t to false, the changelog gives an unspecific error description when it fails:

Unexpected error running Liquibase: java.lang.StackOverflowError