error-on-circular-include-all
Last updated: September 2, 2025
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:
Option | Syntax |
Liquibase properties file (defaults file) | liquibase.errorOnCircularIncludeAll: <true|false> |
Global flow file argument | globalArgs: { error-on-circular-include-all: "<true|false>" } |
Global CLI parameter | liquibase --error-on-circular-include-all=<true|false> update --changelog-file=example-changelog.xml |
JVM system property (JAVA_OPTS environment variable) | Unix: JAVA_OPTS=-Dliquibase.errorOnCircularIncludeAll=<true|false> Windows: JAVA_OPTS=-D"liquibase.errorOnCircularIncludeAll"=<true|false> |
Liquibase environment variable |
|