Troubleshoot the Liquibase Secure server CLI

Installation issues

"An existing .env file was found"

Error: An existing .env file was found. This deployment appears to already be installed.

The CLI prevents accidental reinstalls.

If you meant to upgrade to a new version, use liquibase-platform update instead. It upgrades in place and preserves your data and secrets:

liquibase-platform update --tag your_new_version

If you intentionally want to start fresh, --force overwrites the existing .env:

liquibase-platform install --force --registry your_registry_url

Understand what --force does before running it against a deployment you care about. It regenerates every secret, including the database passwords and LIQUIBASE_PLATFORM_ENCRYPTION_KEY. The new passwords will not match your existing database volumes, and anything already encrypted in the secrets database becomes unreadable. Use --force only when you are discarding the existing data as well.

"Docker Engine 24+ is required"

The CLI checks Docker version during pre-flight. Upgrade Docker Desktop or Docker Engine to 24+.

"Docker Engine is not available" when Docker is running

The CLI prints Docker Engine is not available. Is Docker installed and running? whenever it can't reach Docker. On a Linux host, that includes a user who is not allowed to use Docker while Docker is running. Run docker ps. If it prints permission denied, choose one:

• Use sudo: Run each liquibase-platform command with sudo.

• Add the user to the docker group: Run sudo usermod -aG docker $USER, then log out and back in, or run newgrp docker.

Note: Membership in the docker group gives a user root-level access to the host, so your security team may prefer sudo.

Image pull fails

Error: Failed to pull images. Ensure you are authenticated to the registry.

Re-authenticate, then re-run whichever command you were running:

docker login your_registry_url

For a first-time install, re-run liquibase-platform install --registry your_registry_url. For an existing deployment you are upgrading, re-run liquibase-platform update --tag your_version.

Migration fails during install

The install command leaves databases running for inspection when migrations fail:

Runtime issues

liquibase-platform start says ".env not found"

The stack must be installed first:

liquibase-platform install --registry your_registry_url

Services unhealthy after start

Health check timeout

The API health check has a 90-second timeout during install. If the host is slow:

Log and diagnostics issues

Support bundle generation

If liquibase-platform logs --bundle fails, you can manually collect diagnostics:

Getting help

For issues not covered here, generate a diagnostic bundle (liquibase-platform logs --bundle) when filing a support ticket.