- Concept
- Version ยท 6.0.2
- Manage
Troubleshoot operation reporting
Last updated: November 17, 2026
Common Liquibase Server issues and solutions.
Debug mode
When troubleshooting, enable debug mode to print detailed [LB-PLATFORM-DEBUG] output to the console:
Debug output includes HTTP request details, payload sizes, response codes, and any errors the extension encounters. Disable it after troubleshooting by unsetting the variable or setting it to false.
Extension not loading
The extension uses Java's ServiceLoader mechanism to register itself with Liquibase at startup. If the extension is not loading, no data will be captured and no [LB-PLATFORM] output will appear.
JAR not present. Requires Liquibase Secure 6.0 or later. Confirm the extension is present:
loadingMultiple conflicting JARs. Remove any older versions of the extension JAR from the
internal/extensionsdirectory.ServiceLoader registration missing. If you built the JAR yourself, ensure it includes the
META-INF/services/liquibase.logging.mdc.MdcManagerregistration file.Extension disabled. Verify
LIQUIBASE_PLATFORM_ENABLEDis not set tofalse:echo $LIQUIBASE_PLATFORM_ENABLEDUnknown load failure. Enable debug mode to see detailed startup output:
loading
Connection errors
No data in the platform
the server reports success, but operations do not appear in the dashboard.
Connection identifier mismatch. Verify
LIQUIBASE_PLATFORM_CONNECTION_IDENTIFIERmatches the Identifier field of a registered connection in the dashboard. Case does not matter, sopsqlmatchesPSQL, but every other character must be the same.Wrong workspace. Verify the auth token belongs to the correct workspace.
Stale view. Refresh the dashboard. Operations typically appear within seconds of the command completing.
Filtered view hiding results. Check the All Operations dashboard instead of a filtered view.
Connection refused
Connection refused errors occur when the server tries to send data.
Incorrect or unreachable API URL. Verify the API URL is correct and reachable:
curl http://your-platform-host:3000/api/healthFirewall blocking traffic. Check firewall rules allow traffic from the CLI machine to the API.
Docker network misconfiguration. If running in Docker, ensure containers are on the same network.
Certificate errors
Liquibase prints this when the Java that runs it doesn't trust the server's certificate:
The message calls it a connectivity problem, but the server was reached and Java refused its certificate. A browser lets you accept a certificate it doesn't trust. Java has no such prompt, so a certificate your browser loads after a warning still fails here. This is what happens with the self-signed certificate that liquibase-platform install generates. The command still succeeds, and its operation is written to the recovery file instead of the server.
To fix it, add the server's certificate to the Java that runs Liquibase. See Let Liquibase trust the certificate in Configure TLS certificates for Liquibase Secure server. Two related messages have their own causes:
PKIX path validation failed: The server's certificate changed after you imported it. Import the new certificate.Hostname โฆ not verified: The API URL uses an address the certificate doesn't cover. Use the--domainvalue from the install,localhostor127.0.0.1.
Timeout errors
Timeout errors occur, especially with large operations.
Slow network response. Enable debug mode to see detailed timing:
loadingHigh network latency. Check network latency between the CLI machine and the API.
Report errors
A renamed or relocated report does not appear
A report generated under a custom name or written outside the default directory is still uploaded. The extension reads the report name and path Liquibase resolved for the command rather than assuming the defaults, and it looks for the exact file name instead of matching the default timestamp pattern.
If a report is still missing, check these in order:
Confirm report capture is on. It is enabled by default, and
liquibase.platform.captureReportsturns it off.Check whether
liquibase.platform.reportsPathis set. It overrides the path Liquibase resolved, so a stale value sends the extension to the wrong directory.Run with
liquibase.platform.debugenabled and read the[LB-PLATFORM-DEBUG]line reporting which directory was searched.
Note: Setting liquibase.platform.reportsPath to match --report-path is no longer necessary. Earlier releases required both, and the duplicate value is now only an override.
A report in Amazon S3 or Azure Storage is not uploaded
When the report path is an s3:// or az:// location and the extension cannot read the report, it prints an [LB-PLATFORM-ERROR] line that names the location and the cause, and the run summary adds a Report Not Captured line. A report the extension cannot read never fails the Liquibase command or changes the result recorded for the operation, even with liquibase.platform.failOnError set.
The message after [LB-PLATFORM-ERROR] tells you which fix applies:
No HTML report for this run was found at: The extension found no report it could read at that location. Check the report path, check that the command wrote its report there, and check that the credentials in use can list and read that location.Could not read the HTML report fromwithAccessDeniedException (403): The credentials cannot read that location. On Amazon S3, grants3:ListBucketands3:GetObjecton it. On Azure Storage, grant permission to list and read blobs in the container.Could not read the HTML report fromwithNoSuchBucketException (404): The bucket in the report path does not exist. Check its name.Cannot search for the HTML report at: The report path is a bucket or container root. Point it at a folder inside the bucket or container, or set--report-name.Timed out after 30s reading the HTML report from: The extension stops waiting after 30 seconds. Check that this machine can reach the storage endpoint.
When credentials are missing or rejected, the error line ends with a Cause: that carries the cloud provider's own message, for example that no credentials could be loaded from any provider in the chain.
Run summary errors
Final Status is FAILURE after a run that looked successful
After a run, the extension prints a summary block to stderr under the heading Liquibase Change Intelligence Extension - Summary. Its Final Status line reports the run as a whole. It reads FAILURE when any captured command in the run failed, even when every command after it succeeded. A captured command is one of the Liquibase commands that report to Liquibase Server.
To find the command that failed, read the Commands: section of the summary. It sits after Operation Status: and lists each captured command in the order it ran, with its own result and counts, for example 1. checks run FAILURE (logs 40, severe 0, failures 1). The extension also prints one line as each captured command finishes, such as [LB-PLATFORM] Command 'update' finished: SUCCESS (logs 250, severe 0, failures 0), so a CI log shows each result where it happened. A command that does not report to the server gets no row, and its line says so instead, such as [LB-PLATFORM] Command 'status' is not captured by Change Intelligence.
A captured command fails when one of its changesets fails, when it ends with an error, or when the extension records a failure for it, such as a policy check that finds a blocking violation. A SEVERE message on its own does not fail a command, so a row can read SUCCESS with a severe count above 0. Findings from checks at severity 0 never fail a command. To fix a failed command:
Find the row marked
FAILUREin theCommands:section.Search the output before that command's
finished: FAILUREnotice for the error, the changeset that failed, or the policy check finding that blocked the command.Fix the cause that the error, changeset, or finding names, then run the command again.
Authentication errors
401 Unauthorized
401 Unauthorized responses indicate the API cannot verify the authentication token.
Token not set. Verify your token is set:
echo $LIQUIBASE_PLATFORM_API_KEYExpired, revoked, or suspended token. The response carries a
codeoftoken_expired,token_revoked, ortoken_suspended, and names the token by its name and prefix. Follow the entry for that code.Malformed token value. Ensure there are no extra whitespace or newline characters in the token value.
Deactivated account. A personal access token whose owner's account is deactivated or deleted gets a plain
401 Unauthorizedthat names no token. Ask an administrator to check the account.
token_revoked
A 401 Unauthorized response with the code token_revoked means the token was revoked. Revoking is immediate and permanent, so the same token value never works again. The response names the token in token_name and token_prefix, and gives the date in revoked_at and the reason in revocation_reason.
A service token was revoked or replaced. An administrator revoked the service token, or rotated its service principal, which revokes the previous token. Put the token from the latest rotation in your CI system's secret store, or rotate the service principal for a new one.
The service principal was deleted. The reason is
service_principal_deleted. Create a service principal for the pipeline and use its service token.A personal access token was revoked. You or an administrator revoked it. Create a personal access token and set the new value as
liquibase.platform.apiKeyorLIQUIBASE_PLATFORM_API_KEY.The owner's account was deactivated. The reason is
owner_deactivated. Deactivating an account revokes all of its personal access tokens, and reactivating it restores none of them. Ask an administrator about the account.
token_expired
A 401 Unauthorized response with the code token_expired means a personal access token is past its expiry date, which the response gives in expired_at. Personal access tokens always expire, and service tokens do not.
Create a personal access token to replace it, and set the new value as liquibase.platform.apiKey or LIQUIBASE_PLATFORM_API_KEY. If the expired token was in a pipeline, use a service token there instead, because a personal access token cannot send operation data.
token_suspended
A 401 Unauthorized response with the code token_suspended means an administrator turned off personal access tokens for the workspace named in workspace_name. A suspended token is not revoked. It works again as soon as an administrator turns the setting back on, unless it has expired in the meantime, because its expiry date keeps counting down while it is suspended. Service tokens are never suspended.
403 Forbidden from a service token
A service token must name at least one registered connection or changelog, so the server can file the operation under a project. A 403 response says which rule the operation broke:
No identifier. The operation named neither a connection nor a changelog. Set
liquibase.platform.connectionIdentifierorliquibase.platform.changelogIdentifierin the Liquibase configuration, orLIQUIBASE_PLATFORM_CONNECTION_IDENTIFIERorLIQUIBASE_PLATFORM_CHANGELOG_IDENTIFIERin the environment. One is enough.Different projects. The connection and the changelog belong to different projects. Add them to a common project, or change one of the identifiers.
Out of scope or not registered. The token's projects do not include the connection or changelog the operation named, or it is not registered. Register it, and check which projects the token can write to.
credential_type_mismatch
A 403 Forbidden response with the code credential_type_mismatch means the token is the wrong type for the request. The response names the type the request needs in required_credential_type and the type you sent in supplied_credential_type. Sending operation data needs a service token, so the server refuses a personal access token with the message Personal access tokens are not permitted on this route.
A pipeline uses a personal access token. A personal access token cannot send operation data. Create a service principal for the pipeline and set its service token as
liquibase.platform.apiKeyorLIQUIBASE_PLATFORM_API_KEY.A pipeline still uses a token that a person created before Liquibase Secure 6.0.2. The upgrade to 6.0.2 turned every token that belonged to a person into a personal access token with the same value, so a pipeline that reported with one is now refused. Move the pipeline to a service token in the same way.
Note: On your own machine this refusal is expected. When you run Liquibase locally with a personal access token, Liquibase reports in an INFO line that the results were not sent, and the command's exit code is unaffected.
API root errors
The liquibase.platform.apiUrl setting is the address of your server with /api on the end. Liquibase builds each URL it needs from there, so your value never ends in a resource path such as /operations/ingest.
Telling a configuration problem from a connection problem
Liquibase reports these as four different failures, so the message tells you which one you have before you start debugging the network.
A configuration problem. The message names
liquibase.platform.apiUrland every channel you can set it through, and the run stops before the command does any work.An authorization problem. A 401 or 403 response, covered under Authentication errors above. The root reached the server and the server refused the credentials.
A connectivity problem. A transport failure names the host it could not reach. The root is well formed and nothing answered. A certificate Java doesn't trust is reported this way too. See Certificate errors above.
A not-found problem. A 404 that shows the exact URL that was called. This is usually the root rather than the network, so check the two 404 entries below before looking at firewalls.
No API root is configured
When reporting is enabled and no root is set, Liquibase names the setting and every way you can set it, then stops before running the command.
Set it in one of these three places. A flag beats a system property, which beats an environment variable, which beats the properties file.
liquibase.platform.apiUrlin yourliquibase.propertiesfile.LIQUIBASE_PLATFORM_API_URLas an environment variable.--platform-api-urlon the command line.
The API root is not a usable URL
A value with no scheme, an unsupported scheme, or one that cannot be parsed is rejected while Liquibase validates your configuration, before the command begins. The message quotes the value as you set it, with any embedded credentials removed.
Include the scheme. liquibase.example.com/api is rejected, and https://liquibase.example.com/api is accepted. A trailing slash makes no difference either way.
The API root carries a query string or fragment
A root containing ? or # is rejected at configuration time. Liquibase composes an endpoint by adding the resource path to the end of your root, so a query string would swallow that path and a fragment would drop it.
Remove everything from the ? or # onward. Liquibase rejects the value rather than repairing it, because silently rearranging what you configured is the behavior this setting exists to avoid.
A 404 when the root is missing its API prefix
Liquibase cannot catch this one when it reads your configuration. A root with no API prefix is a perfectly well-formed URL, and behind a reverse proxy it might even be the correct one, so it is only wrong when the server answers.
The 404 names the setting and shows the exact URL that was called. If that URL is missing the prefix your deployment serves the API on, add it to your root. On a standard install the prefix is /api, so the root is https://liquibase.example.com/api rather than https://liquibase.example.com.
A 404 when the root still includes a resource path
This is the same 404 with the opposite cause. If your root already ends in a resource path, Liquibase adds its own on top and asks the server for a path that does not exist.
Look at the URL in the message. A doubled ending such as /api/operations/ingest/operations/ingest means the configured root still carries a resource path. Remove everything after the API prefix, so that https://liquibase.example.com/api/operations/ingest becomes https://liquibase.example.com/api.