Missing Required Argument '--changelog-file' When Running Liquibase Commands

Applies to

• Liquibase Secure (Pro)
• Liquibase Community (Open Source)

Conditions

• Running Liquibase commands that require a changelog file (e.g., validate, update, rollback, updateSQL, etc.)
• Applicable to all execution methods: CLI, Maven, Gradle, flow files, CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, etc.)
• Applicable to all database platforms

Issue Summary

When executing Liquibase commands, the command fails with a validation error indicating that the required --changelog-file argument is missing. This occurs when running commands that require a changelog file but the changelog file path has not been specified in the command configuration.

Error Message

ERROR: Exception Details
ERROR: Exception Primary Class: CommandValidationException
ERROR: Exception Primary Reason: liquibase.exception.CommandValidationException: Invalid argument '--changelog-file': missing required argument

ERROR: Flow file failed validation checks.
Invalid command in stage: Default: 'liquibase' validate: liquibase.exception.CommandValidationException: Invalid argument '--changelog-file': missing required argument

Root Cause

The Liquibase command is missing the required changelog-file parameter. Many Liquibase commands, such as validate, update, updateSQL, rollback, rollbackSQL, status, and others require a changelog file to be explicitly specified.

This parameter must be provided through one of the following methods:

• Command-line argument
• Environment variable
• Properties file
• Build tool configuration (Maven/Gradle)
• Flow file configuration

If the changelog file is not specified through any of these methods, Liquibase cannot locate the changelog file and throws a CommandValidationException.

Resolution

Note: Choose the method that best fits your workflow and execution environment. Ensure the path to your changelog file is correct and accessible from your execution context.

Add the changelog-file parameter to your Liquibase configuration using one of the following methods based on your execution approach:

Option 1: Command-Line Argument

Specify the changelog file directly in the command:

liquibase validate --changelog-file=path/to/changelog.xml

Option 2: Environment Variable

Set the changelog file as an environment variable:

Linux/Mac:

export LIQUIBASE_COMMAND_CHANGELOG_FILE="path/to/changelog.xml"
liquibase validate

Windows:

set LIQUIBASE_COMMAND_CHANGELOG_FILE=path/to/changelog.xml
liquibase validate

In CI/CD workflows (GitHub Actions, GitLab CI, etc.):

env:
  LIQUIBASE_COMMAND_CHANGELOG_FILE: "path/to/changelog.xml"

Option 3: liquibase.properties File

Add the property to your liquibase.properties file:

changelog-file=path/to/changelog.xml

Option 4: Flow File Configuration

If using flow files, specify the changelog-file in the cmdArgs section:

- type: liquibase 
  command: validate 
  cmdArgs: {changelog-file: 'path/to/changelog.xml'}

Or set it globally for all stages:

globalArgs:
  changelog-file: 'path/to/changelog.xml'

stages:
  - type: liquibase 
    command: validate
  - type: liquibase 
    command: update

Option 5: Maven Configuration

Add the changelog file to your Maven plugin configuration:

<plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <configuration>
        <changeLogFile>path/to/changelog.xml</changeLogFile>
    </configuration>
</plugin>

Option 6: Gradle Configuration

Add the changelog file to your Gradle configuration:

liquibase {
    activities {
        main {
            changelogFile 'path/to/changelog.xml'
        }
    }
}