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+.

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.