What are the rules for using search-path with remote files?
Last updated: July 14, 2025
The search path is used to store the base elements of the path to Liquibase changelog files or snapshot files. Changelog files (and a few others) cannot be specified by an absolute path on the file property itself, so the search path is combined with the relative path of the file's property to find these files stored remotely.
For more information, see How Liquibase Finds Files: Liquibase Search Path. You can set the --search-path property in the CLI, within the liquibase.properties file, as an environment variable, or any other standard method for setting a property.
Rules
Below are all of the rules that apply to --search-path
. Review the example use cases and instructions to ensure it is the right avenue for your project.
Multiple searchpaths
If search-path
is set, it is used, and Liquibase will not look in other locations for changelog or snapshot files. Therefore, if some necessary files are located in remote storage and some are local, both locations are required in the search path.
When not specifically configured, by default
--search-path
looks for changelogs in the current working directory.When
--search-path
is configured, only the locations explicitly defined in--search-path
are used to locate changelogs.Multiple
--search-path
locations are comma-separated and processed in order.
S3 example:
--search-path=s3://myBucket/demo,C:\Users\Me\demo
Azure example:
--search-path=az://myContainer/demo,C:\Users\Me\demo
If multiple
--search-path
locations are specified, Liquibase may find two or more changelog files with the same name. To determine how Liquibase behaves in this case, see the "Duplicate File Mode" section of this document.
Note: If the changelog references resource files in multiple directories, it may be easier to define the --search-path
as an environment variable. This prevents the --search-path
property from making the command line unreadable. The --search-path
environment variable is LIQUIBASE_SEARCH_PATH
.
Multiple --search-path
locations example:
--search-path=s3://myBucket/path,.localfiles
Note: s3://myBucket/path
is the first location and .localfiles
is the second location that search-path
will find the files.
Duplicate File Mode
The --
duplicate-file-mode
property determines how Liquibase behaves when multiple changelogs are found in the multiple locations specified in the --search-path
property. By default, an ERROR
will be thrown to halt execution, but --duplicate-file-mode
can be set to SILENT
, DEBUG
, INFO
, or WARN
instead, settings which log the issue but do not halt execution. In these cases, it uses the first changelog file found in a sequential processing of --search-path
locations.
Error Response
The ERROR
response states two files are found and Liquibase will not use either file. It will then suggest you rename the file or correct the value you specify for --search-path
, and then re-run the command.
Example: Default behavior of --duplicate-file-mode
when changelog.xml
is located in two --search-path
directories.
In this example, a changelog named changelog.xml
is located in both s3://myBucket/demo
and in s3://myBucket/demo2
.
liquibase --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml
Liquibase console output shows an error and does not execute the update-sql
command.
Unexpected error running Liquibase: Error changelog.xml
- Caused by: Found 2 files
with
the path 'changelog.xml':
- s3:
//myS3Bucket/demo/changelog.xml
- s3:
//myS3Bucket/demo2/changelog.xml
Search Path:
- s3:
//myS3Bucket/demo/changelog.xml
- s3:
//myS3Bucket/demo2/changelog.xml
You can limit the search path to remove duplicates
with
the liquibase.searchPath setting. Or,
if
you KNOW these are the exact same file you can set liquibase.duplicateFileMode=WARN.
liquibase --duplicate-file-mode=ERROR --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml
results in update-sql
exiting with an ERROR
that duplicate changelog.xml
file was located.
Example: Behavior when --duplicate-file-mode
set to ERROR
and changelog.xml
is located in two search-path
directories
Although the default for --duplicate-file-mode
is ERROR
, you can explicitly configure the setting to throw an error. In this example, a changelog named changelog.xml
is located in both s3://myBucket/demo
and in s3://myBucket/demo2
.
liquibase --duplicate-file-mode=ERROR --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml
Liquibase console output shows an error and does not execute the update-sql
command.
Unexpected error running Liquibase: Error changelog.xml
- Caused by: Found 2 files
with
the path 'changelog.xml':
- s3:
//myS3Bucket/demo/changelog.xml
- s3:
//myS3Bucket/demo2/changelog.xml
Search Path:
- s3:
//myS3Bucket/demo/changelog.xml
- s3:
//myS3Bucket/demo2/changelog.xml
You can limit the search path to remove duplicates
with
the liquibase.searchPath setting. Or,
if
you KNOW these are the exact same file you can set liquibase.duplicateFileMode=WARN.
Warn response
The WARN
response states two files are found and it will automatically use the first file found.
Example: Behavior when --duplicate-file-mode
set to WARN
and changelog.xml
is located in two --search-path
directories.
To explicitly ignore duplicate changelogs in the searchpath, configure --duplicate-file-mode
to WARN
. In this example, a changelog named changelog.xml
is located in both s3://myBucket/demo
and in s3://myBucket/demo2
.
liquibase --duplicate-file-mode=WARN --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml
Liquibase console output shows a warning. The update-sql
command is executed using the changelog in s3://myBucket/demo
.
Found 2 files
with
the path 'changelog.xml':
- s3:
//myS3Bucket/demo/changelog.xml
- s3:
//myS3Bucket/demo2/changelog.xml
Search Path:
- s3:
//myS3Bucket/demo/changelog.xml
- s3:
//myS3Bucket/demo2/changelog.xml
You can limit the search path to remove duplicates
with
the liquibase.searchPath setting.
To fail when duplicates are found, set liquibase.duplicateFileMode=ERROR
Choosing: s3:
//myS3Bucket/demo/changelog.xml