Troubleshoot operation reporting

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.

1. JAR not present. Requires Liquibase Secure 6.0 or later. Confirm the extension is present:

   Copy code to clipboard

   loading

2. Multiple conflicting JARs. Remove any older versions of the extension JAR from the internal/extensions directory.

3. ServiceLoader registration missing. If you built the JAR yourself, ensure it includes the META-INF/services/liquibase.logging.mdc.MdcManager registration file.

4. Extension disabled. Verify LIQUIBASE_PLATFORM_ENABLED is not set to false:

   Copy code to clipboard

   echo $LIQUIBASE_PLATFORM_ENABLED

5. Unknown load failure. Enable debug mode to see detailed startup output:

   Copy code to clipboard

   loading

Connection errors

No data in the platform

the server reports success, but operations do not appear in the dashboard.

1. Connection identifier mismatch. Verify LIQUIBASE_PLATFORM_CONNECTION_IDENTIFIER exactly matches the Identifier field of a registered connection in the dashboard.

2. Wrong workspace. Verify the auth token belongs to the correct workspace.

3. Stale view. Refresh the dashboard. Operations typically appear within seconds of the command completing.

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

1. Incorrect or unreachable API URL. Verify the API URL is correct and reachable:

   Copy code to clipboard

   curl http://your-platform-host:3000/api/health

2. Firewall blocking traffic. Check firewall rules allow traffic from the CLI machine to the API.

3. Docker network misconfiguration. If running in Docker, ensure containers are on the same network.

Timeout errors

Timeout errors occur, especially with large operations.

1. Slow network response. Enable debug mode to see detailed timing:

   Copy code to clipboard

   loading

2. High 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:

1. Confirm report capture is on. It is enabled by default, and liquibase.platform.captureReports turns it off.

2. Check whether liquibase.platform.reportsPath is set. It overrides the path Liquibase resolved, so a stale value sends the extension to the wrong directory.

3. Run with liquibase.platform.debug enabled and read the [LB-PLATFORM-DEBUG] line reporting which directory was searched.

Note: In Liquibase Secure 6.0.0, the extension cannot read a report stored in Amazon S3 or Azure Storage. When the report path starts with s3:// or az://, the debug line shows the path with the scheme collapsed, for example s3:/bucket/reports, and no report is uploaded. Point the report path at a local directory instead.

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.

Authentication errors

401 Unauthorized

401 Unauthorized responses indicate the API cannot verify the authentication token.

1. Token not set. Verify your token is set:

   Copy code to clipboard

   echo $LIQUIBASE_PLATFORM_API_KEY

2. Expired or revoked token. Regenerate the token in the server web dashboard.

3. Malformed token value. Ensure there are no extra whitespace or newline characters in the token value.

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.

1. A configuration problem. The message names liquibase.platform.apiUrl and every channel you can set it through, and the run stops before the command does any work.

2. An authorization problem. A 401 or 403 response, covered under Authentication errors above. The root reached the server and the server refused the credentials.

3. A connectivity problem. A transport failure names the host it could not reach. The root is well formed and nothing answered.

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

1. liquibase.platform.apiUrl in your liquibase.properties file.

2. LIQUIBASE_PLATFORM_API_URL as an environment variable.

3. --platform-api-url on 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.