error-on-circular-include-all

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.

Uses

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.

Syntax

You can set this parameter in the following ways:

liquibase.errorOnCircularIncludeAll: <true|false>

stages:
  Default:
    actions:
      - type: liquibase
        command: update
        globalArgs: { error-on-circular-include-all: "<true|false>" }

liquibase
 --error-on-circular-include-all=<true|false> update
 --changelog-file=example-changelog.xml

JAVA_OPTS=-Dliquibase.errorOnCircularIncludeAll=<true|false>

LIQUIBASE_ERROR_ON_CIRCULAR_INCLUDE_ALL=<true|false>

For more information, see Working with Command Parameters.

Output

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