Troubleshoot licensing on Change Automation

Working through any of the messages below takes shell access to the node showing it, and knowing which of the three license sources you intended that node to use.

A Secure command is refused

The command stops before doing any work. The message names the command you ran and says why your license was not accepted.

LB-LIC-0021 means no license is configured, rather than one that failed verification or expired. Set one of the three sources and run liquibase license status to confirm which one took effect. See License a Change Automation node.

Every LB- code Liquibase emits, including the rest of the LB-LIC- range, is listed in Error codes and exit codes.

The license endpoint refuses the node

The run is refused with LB-LIC-0026, which says the license endpoint refused the request because liquibase.platform.apiKey does not hold a key it accepts.

The server is running and reachable, but it does not answer a node that does not send a service principal token. Set liquibase.platform.apiKey, or the LIQUIBASE_PLATFORM_API_KEY environment variable, to the token of a service principal created in this installation, then run liquibase license status again. See Create a service principal for a CI/CD pipeline.

If the node already sends a token, check that it was created in the same installation the endpoint belongs to and that it is still valid.

You see LB-LIC-0026 only when the node has no license file or license contents to fall back to. A node that also has one keeps running on it without any message, and it does not report usage. See The wrong source is being used, below.

A license file is refused as an add-on

LB-LIC-0008 means the license file or license contents the node is using is an add-on. An add-on only adds to a base, so it cannot license a node on its own. Point the node at a base, renewal, or consolidated license instead, or use the license endpoint, which combines the base and its add-ons for you. See License a Change Automation node.

The wrong source is being used

liquibase license status reports Source as something other than what you configured. A node with a file on disk and an endpoint configured will report whichever Liquibase resolved, and it may not be the one you changed most recently.

Remove the source you do not want rather than adding another. Setting several is not an error, which is exactly why it is hard to notice.

If Source names the license endpoint together with a file or environment variable, the endpoint did not supply a license and the node fell back to its own. Liquibase always tries the endpoint first, and falls back when the endpoint cannot be reached, refuses the node's service principal token, or serves a license that fails verification. The most common cause is a missing liquibase.platform.apiKey. Set it to the token of a service principal created in this installation, then run liquibase license status again.

The checks show command stops without finishing

The first time you run liquibase checks show in a folder that has no checks settings file, Liquibase asks whether to create one and waits for your answer:

WARNING: No default checks-settings file detected. Would you like to create and automatically use 'liquibase.checks-settings.conf' ?

This is not a licensing problem. Answer the question to continue:

• Press Enter to accept the default. Liquibase creates liquibase.checks-settings.conf and sample checks package files in the current folder, then prints the checks.

• Type n and press Enter to exit without creating any files.

If the window shows nothing at all, press Enter once. If it still does not respond, press Ctrl+C and run the command again.

A usage tracking warning appears

The command succeeds and its output ends with a warning like this one:

WARNING: Usage tracking to http://your_server_host failed after 1 tries (HTTP 401, the collector does not accept the key in liquibase.platform.apiKey). The database operation is unaffected.

It means the node could not report its usage. Usage reporting does not fail a deployment unless liquibase.license.tracking.required is set to true, and it is not a licensing problem. A node can be correctly licensed and still fail to report usage.

If the warning names HTTP 401 or HTTP 403, Liquibase Secure server did not accept the node's service principal token. Set liquibase.platform.apiKey to the token of a service principal created in this installation. See Create a service principal for a CI/CD pipeline.

If the warning names HTTP 404, the node reached the host but not the address that receives usage. The warning shows only the host, so if you set liquibase.license.tracking.url (or its older name liquibase.license.utility.url), check its value. It takes the base URL of the address that receives usage, and Liquibase adds /v1/track itself, so a value that already ends in /v1/track is sent to /v1/track/v1/track. Remove the suffix, for example https://your_server_host/api/license-tracking. When a node gets its license from the license endpoint and the response names a usage tracking endpoint, Liquibase sends usage there and does not read liquibase.license.tracking.url at all. In that case the property is not what caused the 404, so check it only when the response names no tracking endpoint. For any other error, check that the node can reach the address the warning names.

Usage that never arrives affects the central utilization figures, not the node. Nothing on the node needs repairing and no run needs repeating.

If liquibase.license.tracking.required is set to true, the same failure stops the run with LB-TRK-0001 and exit code 70 instead of printing the warning. Usage is sent after the operation finishes, so the database changes the run made stay in place. Fix the cause the message names, or unset the setting to let runs continue with a warning. To keep usage that could not be delivered and send it on the next run, set liquibase.license.tracking.spoolDir. See License a Change Automation node.

Usage does not appear on the Utilization tab

A node can run without any warning and still report nothing. On the node, check that:

• liquibase license status reports Source as the license endpoint only. If it also names a file or environment variable, the node fell back to its own license and does not report usage. A node licensed from a file or license contents does not report usage to Liquibase Secure server.

• liquibase.license.tracking.enabled is set to true. Without it, the node does not report usage.

• liquibase.platform.apiKey holds a service principal token from this installation.

See License a Change Automation node.

A utilization or expiry warning appears

These are advisory and appear in normal output.

• Utilization warns at 80 percent of licensed capacity and goes critical at 90 percent, unless an administrator has set different thresholds on Liquibase Secure server. These are fleet figures, so they appear only on a node reading its license from an endpoint. A node licensed from a file shows no utilization warning, which is expected rather than a fault.

• Expiry is announced 90 days before the term ends. On a node that reads its license from an endpoint, the lead time is the expiration notice an administrator sets on Liquibase Secure server. A node licensed from a file always uses 90 days.

• After the term ends, a license that states a grace period keeps working until the grace period ends, and every run warns: The license term ended on <date>; the grace period runs until <date>. Once the grace period ends, Liquibase commands are refused with LB-LIC-0018.

None of these warnings fails a run or changes an exit code. Treat them as a procurement signal rather than an incident. The 90 day expiry notice exists so that an air gapped installation has time to obtain a renewal from your Liquibase account team.

Capacity itself is never evaluated on the node, so there is no per-run message telling you a single run went over. Exceeding capacity is worked out centrally from reported usage.

An endpoint is unreachable but runs still succeed

Expected. A cached endpoint response stays usable while it is within its time to live, so an outage does not stop a pipeline.

Note that the cache and the license term are separate clocks. A fresh cache never revives an expired license, and a stale cache never shortens a valid one. If runs succeed during an outage, the license is genuinely still valid.