- Concept
- Version · 6.0.2
- Create
Troubleshoot the Liquibase Secure server CLI
Last updated: November 17, 2026
Common CLI issues, error messages, and how to resolve them.
Installation issues
"An installation or its data already exists"
install stops with LB-SEC-INS-0011 when the directory already has a .env file, or when the host still has the containers or data volumes of an earlier deployment. This prevents an accidental reinstall:
If you meant to upgrade to a new version, use liquibase-platform update instead. It upgrades in place and keeps your data and secrets.
Be sure to:
Replace
your_license_filewith the path to your license file, or the directory that holds it. For example,liquibase.licReplace
your_new_versionwith the version to upgrade to. For example,6.0.2
liquibase-platform update --license your_license_file --tag your_new_versionIf you want to start fresh, uninstall first. This removes the containers, the data volumes and the generated files, so make sure you no longer need the data:
liquibase-platform uninstall
liquibase-platform install --license your_license_fileUse --force only to recover from an install that stopped partway. When the install process is killed before it finishes, for example by a hard kill, a crash, a dropped SSH session or a power loss, it can leave a .env file with no deployment behind it. --force overwrites that leftover file. It cannot replace an existing deployment or its data, so install --force over one stops with the same error. If you install from your own registry, add --registry your_registry_url to the install command.
One Docker host runs one deployment. install also stops with LB-SEC-INS-0011 in a new directory when the host still has another deployment's data volumes or containers. The message lists them:
To keep using that deployment, run its commands from its own deployment directory, or pass that directory with --dir. To replace it, run liquibase-platform uninstall in its deployment directory first, which deletes its data. To run a second deployment, use another Docker host.
If that deployment directory no longer exists, uninstall has nowhere to run and stops with LB-SEC-INS-0018. Remove what the message lists with Docker instead. This deletes that deployment's data, so make sure you no longer need it.
Be sure to replace your_project_name with the Compose project the message names, and your_volume_names with the volumes it lists, separated by spaces. If the message lists containers, run docker compose -p your_project_name down first. Then run docker volume rm your_volume_names, and run install again.
"Docker is not available"
install checks Docker before it changes anything and stops with LB-SEC-INS-0010 when Docker Engine does not respond, Docker Compose v2 is not installed, or Docker Engine is older than 24. Every command also stops before it runs Docker Compose when Docker Compose is older than 2.20, and names the version it found. Install or start Docker Engine 24 or later with Docker Compose 2.20 or later, then run the command again.
When the Cause: line says permission denied, Docker is running and your user is not allowed to use it. On a Linux host, give the user access to Docker, then run the command again.
pull --to also needs the Docker buildx plugin. Docker Desktop includes it. On Docker Engine, install the docker-buildx-plugin package.
"Invalid command-line usage"
Every command stops with LB-SEC-INS-0020 when a flag or its value is not valid, and the message says which. For example, a --tag that is not a version:
Run the command with --help to see the flags it accepts. These messages have their own fix:
release … can't run the third-party images from --registry; install it without --include-third-party: That release, such as 6.0.0, takes the nginx, TimescaleDB, PostgreSQL and Redis images from Docker Hub only. Install it without--include-third-party, on a host that can reach Docker Hub or a Docker Hub mirror.update has upgrade notices to confirm and no terminal to ask on:updatefound upgrade notices and has no terminal to ask you on, for example in a pipeline. It stops before it changes anything. Run it in a terminal, or add--non-interactiveto accept the notices.--db-host needs the database password in the LIQUIBASE_PLATFORM_DB_PASSWORD environment variable, not on the command line: SetLIQUIBASE_PLATFORM_DB_PASSWORDin the environment, then runinstallagain.
Image pull fails
install, update and pull stop when they cannot pull an image, and print an error code with a suggestion. The command exits with 1 when the fix is yours and 70 for a system failure. The code tells you which side failed:
Code | What it means | What to do |
|---|---|---|
| oci. | Use the most recent license file Liquibase sent you. If it is current, contact Liquibase support with the error output. |
| The host cannot reach the registry. | Allow outbound HTTPS to the hosts listed after this table. Set |
| The pull itself failed, for example because the disk is full, the network dropped, or your own registry refused the pull. | Free disk space or fix the network. If your registry refused the pull, run |
| Your registry refused an image that | Run |
| The registry answered with a server error. | Wait a few minutes and run the command again. If it keeps failing, contact Liquibase support with the code and the request ID. |
install, update and pull need outbound HTTPS to these hosts:
api.keygen.sh, for the deployment filesoci.liquibase.com, for the Liquibase imageskeygen-dist.c3c9112df8df715f42d1162cdce5dba1.r2.cloudflarestorage.com, where the deployment files and image layers download fromDocker Hub, for the nginx, PostgreSQL and Redis images. Not needed if you copied them to your own registry with
pull --to --include-third-partyand install with--include-third-party.
When pull --to copies a third-party image, such as nginx, and Docker Hub limits or refuses the pull, the error is LB-SEC-INS-0012 and names the image:
Docker Hub limits anonymous pulls per IP address. Run docker login docker.io on the host, or copy that image into your registry another way, then run the command again.
start and migrate never pull. When an image is missing from the host, they stop with LB-SEC-INS-0012 and tell you to pull it with liquibase-platform update --license your_license_file --tag your_version.
"The external database … did not accept the connection"
install, update and migrate stop with LB-SEC-INS-0041 when an external primary database doesn't accept the connection the migrations use. They check before they change anything, so nothing has changed. The message names the host and port, and ends with one of these reasons:
authentication failed: The user or password is wrong, or the database's
pg_hba.confdoesn't accept connections from this host.database does not exist: The database name is wrong, or the database hasn't been created yet.
connection refused: The host has nothing listening on that port.
unreachable: The host name doesn't resolve, or the host can't be reached from Docker.
TLS failure: The database doesn't support TLS, its certificate comes from a CA that isn't in
db-tls/, or the certificate doesn't cover the host name.changelog lock held by another run: Another
install,updateormigrateis running against the database. The check waits about a minute before it stops.unexpected reply: The database refused for another reason, and the message quotes its first line. A user without CREATE on the
publicschema getspermission denied for schema publichere.
Fix the setting the reason points to, then run the same command again. For install, that is the --db-* options. After that, it is the LIQUIBASE_PLATFORM_DB_* settings in .env and the password in secrets/db_password. You don't need install --force, because the command wrote no files.
A migration fails
When a migration fails during install, the command stops with LB-SEC-INS-0014, rolls back and removes its containers and volumes. There are no logs to read afterward. Use the output above the error and its Cause line to find the problem, fix it, then run the install again.
A database that does not become healthy in time stops install before any migration runs, with LB-SEC-INS-0013, and rolls back the same way.
When a migration fails during update, your data is intact and the databases keep running so you can inspect them. The error names the database. Check it with liquibase-platform logs --service db or liquibase-platform logs --service secrets-db, fix the cause, then run the update again.
"Version … is newer than this liquibase-platform CLI"
install and update stop with LB-SEC-INS-0038 when the --tag you asked for is newer than the CLI you are running, because a newer release can need steps this CLI doesn't know. For example, a 6.0.2 CLI asked for 6.0.3 prints ERROR [LB-SEC-INS-0038] Version 6.0.3 is newer than this liquibase-platform CLI (6.0.2). Download the CLI archive for that release, then run the same command with its CLI. Nothing has changed.
"Couldn't read the upgrade notices"
update reads the upgrade notices from both databases before it changes anything, and starts a stopped bundled database itself. LB-SEC-INS-0037 means it couldn't reach one. The message names the database and what went wrong:
update-sql failed: The database runs, but Liquibase couldn't read the changelog from it. A password authentication failure means
.envorsecrets/no longer matches these databases, so restore the files they were created with. Check the database with./liquibase-platform logs --service db, or--service secrets-db.could not be started: Docker couldn't bring the database container up. The cause under the message says whether Docker isn't running or the image couldn't be pulled.
is not running: The database container is paused, dead or restarting, which
updateleaves alone. Unpause it withdocker unpauseand the container name the suggestion gives, or read why it stopped withdocker logs, then runupdateagain.
Nothing has changed at this point. Whatever was running before update still runs.
The PostgreSQL 17 upgrade stops
When a release moves the bundled databases to PostgreSQL 17, update copies them to new volumes before it migrates them. LB-SEC-INS-0032 and LB-SEC-INS-0034 stop it after the copy has started. The other codes in this table stop it before it changes anything, with the previous version still running.
Code | What it means | What to do |
|
| Run |
|
| Free space on the filesystem that holds the Docker volumes, then run |
|
| Set |
|
| Merge your changes into |
|
| Upgrade it to PostgreSQL 17 through your provider, then run the command again. |
|
| Check that the database is running, is reachable from Docker and is not locked by another |
|
| Remove or fix the setting on the previous version, then run |
|
| Pull the image the message names, or start the previous version once, then run |
|
| Fix the cause the error gives, then run |
|
| To upgrade again from the previous version's data, back up the volume the message names, remove it with |
|
| Pass a release on PostgreSQL 17 or later. To go back to the previous version, follow Upgrading the databases to PostgreSQL 17. |
"Could not remove the TimescaleDB extension"
update and migrate stop with LB-SEC-INS-0040 when they cannot remove the TimescaleDB extension. Releases that ran the bundled database on the TimescaleDB image installed it. Before the migrations, both commands remove the extension from the postgres database, then from the platform database when LIQUIBASE_PLATFORM_DB_NAME names another, then from template1. They stop at the first database where the removal fails, and the message names it.
The removal most often fails because the database is not reachable or .env no longer matches it. No migration has run, and your data is intact. The databases stay running so you can inspect them. Read the output under the error and ./liquibase-platform logs --service db, fix the cause, then run the same command again. The removal is safe to repeat.
License and download issues
install, update and pull use your license file to download the deployment files and pull the images. None of these errors changes an existing deployment, and install removes what its run created. Fix the cause, then run the same command again.
A license error stops the command
The error names the code and the license, and the suggestion under it says what to check. For example, a file that is not a Liquibase license file:
ERROR [LB-SEC-INS-0001] License file not found or unreadable: ../notalicense.lic (no license file armor)
Suggestion: Check the path passed to --license and that this user can read the file.Code | What it means | What to do |
|
| Check the path and that the user running the CLI can read the file. Use the license file exactly as Liquibase sent it. |
|
| Pass the license file Liquibase issued for Liquibase Secure server. |
|
| Use the most recent license file Liquibase sent you. If it is current, contact Liquibase support with the request ID the CLI prints. |
|
| Renew the license, import the new file in the console, then run the command again with the new file in |
|
| Ask your Liquibase account team to reinstate the license, then run the command again. |
|
| Use the production license file Liquibase issued for this server. |
|
| Check |
"Deployment file … failed its check"
install, update and pull stop with LB-SEC-INS-0009 when a deployment file does not match what Liquibase signed. The message names the file and the check it failed, filename, checksum or signature. The CLI wrote nothing. Run the command again, and if it fails again, report the code and the version to Liquibase support. With --files, the file changed after pull --files saved it, so save the release again with pull --files and copy the directory over unchanged.
cannot execute binary file when you run ./liquibase-platform
You downloaded the CLI archive for another operating system or architecture. The error can name .cli/bin/node, or read Exec format error. Run uname -sm, then download the archive that matches it. On Windows, use the linux-x64 archive inside WSL2.
Runtime issues
"No installation found"
start, update, stop and the other commands that work on an installed deployment stop with LB-SEC-INS-0018 when they find no deployment. The message names the directory the command checked and the reason:
no docker-compose.ymlor.env is missing: The directory holds no deployment. Run the command from the deployment directory, pass--dir, or setLIQUIBASE_PLATFORM_DIR. ALIQUIBASE_PLATFORM_DIRthat names another directory gives this reason too, even when you run the command from the deployment directory, so check it withecho $LIQUIBASE_PLATFORM_DIR.the recorded deployment ... has none: The directoryinstallrecorded no longer holdsdocker-compose.yml, because the deployment was moved or deleted. Pass--dirwith its new location, or setLIQUIBASE_PLATFORM_DIRto it. Onlyinstallwrites the record.the recorded deployment ... is not used without a prompt:uninstall --non-interactiveandstop --reset --non-interactivenever use the directoryinstallrecorded, because nothing would confirm which deployment they delete. Pass--dir, setLIQUIBASE_PLATFORM_DIR, or run the command from the deployment directory.
If you have not installed yet, install first.
Be sure to:
Replace
your_license_filewith the path to your license file, or the directory that holds it. For example,liquibase.lic
liquibase-platform install --license your_license_fileA port is already in use
install, start and update check the HTTP and HTTPS ports before they change anything, and stop with LB-SEC-INS-0022 if another process holds one. The message names the port, and the container when a Docker container holds it. When both ports are taken, the Cause line names the second:
Either stop the process holding the port, or move Liquibase Secure server to other ports:
For
startandupdate, setLIQUIBASE_PLATFORM_HTTP_PORTandLIQUIBASE_PLATFORM_HTTPS_PORTin.env, and add the HTTPS port toLIQUIBASE_PLATFORM_WEB_URLandLIQUIBASE_PLATFORM_API_URL.For
install, pass--http-portand--https-port. The URLs thatinstallwrites to.envfollow the HTTPS port.
Then run the command again. A taken port stops update before it pulls images or changes .env, so nothing has changed.
If an earlier start failed and left the proxy container broken, start and update remove it and create it again, so you do not need to clean it up yourself.
liquibase-platform start says secret files are missing
A deployment whose docker-compose.yml file reads its secrets from files needs all four files in secrets/. When one is missing, liquibase-platform start and liquibase-platform migrate write it again from the value in .env, if .env still holds one, and say so. When .env no longer holds the value, the command stops with This deployment reads its secrets from secrets/, and these files are missing: followed by the missing files.
Those files hold the only copy of the database passwords and keys the deployment was installed with. Restore them from your backup of secrets/. If update moved the secrets out of .env on this host, .env.bak still holds them as plain values.
The platform did not become reachable
When the API does not answer through the proxy, install, start and update stop with LB-SEC-INS-0015 instead of reporting that the platform is running. What to do next depends on the command:
startandupdateleave the stack running and your data intact. Runliquibase-platform status, thenliquibase-platform logs --service nginxandliquibase-platform logs --service apito see which service is down. Runliquibase-platform startonce the cause is fixed.installrolls back and removes its containers and volumes, so there are no logs to read. Use the error and itsCauseline to fix the problem, then run the install again.
A web service that is slow to become healthy does not stop install or start. The command prints a warning and suggests liquibase-platform logs --service web.
Liquibase reports PKIX path building failed
The server is running, but the Java that runs Liquibase doesn't trust the server's certificate, such as the self-signed certificate install generates. Liquibase prints:
The Liquibase command still succeeds, and its operation goes to the extension's recovery file instead of the server. On each machine that runs Liquibase, add the server's certs/server.crt file to a truststore that Liquibase's Java reads, as Let Liquibase trust the certificate describes. There are two ways:
A copy of the Java's truststore: Copy that Java's
cacertsfile, import the certificate into the copy withkeytool -importcert, and point Liquibase at the copy with-Djavax.net.ssl.trustStoreand-Djavax.net.ssl.trustStorePasswordinJAVA_OPTS. Theliquibaselauncher passesJAVA_OPTSunquoted, so the path to the copy must not contain spaces.The Java's own truststore: Import the certificate with
keytool -importcert -cacerts. This affects every program that runs on that Java, and the import is lost when that Java is upgraded or replaced.
When the message contains No subject alternative, the certificate is trusted but does not cover the address in LIQUIBASE_PLATFORM_API_URL. Set it to the host name you passed to --domain, for example https://your_domain/api.
The server still presents the old TLS certificate
The proxy reads certs/server.crt and certs/server.key only when its container starts, and liquibase-platform start leaves a running proxy as it is. After you replace the certificate files, run liquibase-platform stop, then liquibase-platform start. If machines that run Liquibase trusted the old certificate, import the new one into their truststores too.
Liquibase reports "names neither X-Connection-Identifier nor X-Changelog-Identifier"
A service principal's token files each operation under a project, so Liquibase has to name the database connection or the changelog the operation belongs to. When it names neither, the server answers with a 403, and Liquibase prints:
The Liquibase command still succeeds, and the operation goes to the extension's recovery file. Set liquibase.platform.connectionIdentifier or liquibase.platform.changelogIdentifier in the Liquibase configuration, or LIQUIBASE_PLATFORM_CONNECTION_IDENTIFIER or LIQUIBASE_PLATFORM_CHANGELOG_IDENTIFIER in the environment. One is enough. Its value must name a connection or changelog in a project the service principal is scoped to.
Requests fail with 503 "Database connection pool timed out"
The API waits up to LIQUIBASE_PLATFORM_CONN_TIMEOUT_MILLIS, 5000 milliseconds by default, for a free connection to its database. When every connection stays busy for that long, the API answers the request with a 503 response and the message Database connection pool timed out. Other requests keep being served, and the API recovers by itself once connections are released, so you do not need to restart it.
To find the cause, run liquibase-platform logs --service api and find the exceptions_filter_caught line for the failed request. Its poolState shows the pool's total, idle, waiting and max connections. When idle is 0 and total equals max, every connection was in use. Check the database's pg_stat_activity view for long-running transactions or lock waits.
If the load is expected, raise LIQUIBASE_PLATFORM_DB_POOL_MAX within the database's max_connections setting, or raise LIQUIBASE_PLATFORM_CONN_TIMEOUT_MILLIS, as Database connections describes. Then run liquibase-platform start, which recreates the API with the new settings.
Services unhealthy after start
Health check timeout
install, start and update give the API 90 seconds to pass its health check, then give the proxy 30 seconds. On a slow or busy host the API can need longer, and the command stops with LB-SEC-INS-0015 and no healthy answer within 90s. Check whether the API is still starting and whether the host is short of memory or CPU:
Free up memory or CPU on the host, or move to a larger host, then run the command again.
A service reports was not health-checked
install, start and update read each service's health from its Docker Compose healthcheck. When a service's entry in docker-compose.yml has no healthcheck, the command prints one warning for that service, such as nginx was not health-checked: its service in docker-compose.yml has no healthcheck, and carries on as long as the container stays up. A container that exits or keeps restarting still stops the command with LB-SEC-INS-0015.
The healthcheck is missing when docker-compose.yml comes from an earlier release, or when update kept your edited file and wrote the release's copy beside it as docker-compose.yml.new. To get the check back, merge the healthcheck blocks from docker-compose.yml.new into docker-compose.yml, then run liquibase-platform start.
The nginx healthcheck runs curl inside the container. If you set NGINX_IMAGE to your own image, keep curl in it, or nginx reports unhealthy on a working proxy.
Sign-in issues
A password reset email never arrives
Outbound email is off until LIQUIBASE_PLATFORM_SMTP_HOST is set in .env, so no password reset email arrives. The Forgot password? page still says to check your email, and tells the user to contact their administrator.
To check, an administrator goes to Administer > Authentication. The Email delivery card reads Not configured when email is off. See Manage authentication settings.
To let the user back in now, create a one-time reset link on the Docker host with liquibase-platform reset-password. See Command reference.
To turn email on, set the SMTP settings in .env, then run liquibase-platform start, which recreates the API with the new settings. Password reset and address verification emails then arrive.
Log and diagnostics issues
Support bundle generation
If liquibase-platform logs --bundle fails, you can manually collect diagnostics:
These files are not redacted. Check them for passwords, keys and tokens before you send them.
Getting help
For issues not covered here, generate a diagnostic bundle (liquibase-platform logs --bundle) when filing a support ticket.