Licensing updates: your key stays put, and CI instances stop eating activations

Three licensing updates shipped in October. Directus 12.5, released October 7, keeps your license key when a license check fails. Earlier versions deleted it, so recovering meant finding the key and entering it again. 12.5 also tells admins in the app what went wrong and when the license lapses. On October 8 the licensing service started holding every new activation in a pending state for its first 24 hours, so short-lived CI and test instances no longer use up an activation slot. Directus 12.6, released October 27, brings those warnings into the sidebar.

Both changes come from what self-hosted users told us after v12 launched. Instances dropped to Core without warning, and the license key was gone from the database, so someone had to find it and paste it back in. Teams running CI pipelines saw every test instance take an activation. That hurts most on smaller plans.

A failed license check no longer costs you your license

Before 12.5, a failed refresh left your license running only until its token expired, roughly 7 days later, with no warning in the app. Once the token lapsed, or if the check failed at boot, Directus deleted the key and token and moved the project to Core.

12.5 handles each case on its own terms (#28331):

• A failed license request keeps your current key and token in effect, and a scheduled license check retries it.

• A stored key that isn't in effect yet is retried roughly every hour.

• If the stored token fails verification, Directus asks the licensing service again with your key before it changes anything.

• Only a canceled or suspended license clears the token. The key stays, so you can reactivate without hunting for it.

Admins see what went wrong, and by when to fix it

When a license can't be renewed but is still in effect, admins now see a warning with the date it lapses. If the project does drop to Core, the downgrade notice names the reason. Before 12.5, only expired, canceled and suspended licenses showed anything in the app (#28241).

In 12.5, these notices appear in Settings > License. Directus 12.6 also shows them in the sidebar with the number of days left before the license lapses, so admins see a licensing problem without going looking for it (#28394).

Here's what each warning looks like and what to do about it.

Licensing service can't be reached

Directus couldn't renew the license because it can't reach the licensing service. The license keeps working until the date shown, and Directus keeps retrying on its own. If the warning doesn't clear within a day, check environment's firewall or network policies and make sure it's able to reach licensing.directus.com.

License linked to a different project or URL

The license was activated for a different project ID or URL than this environment is using, for example because PUBLIC_URL changed after activation. Check that your project URL matches the URL the key was activated with.

Activation limit reached

Every activation on your plan is in use, so this environment couldn't get one. Deactivate the license on an environment you no longer use, then retry.

License key no longer valid

The licensing service doesn't recognize the key. Check the key in Settings > License, or add a new one.

Canceled or suspended

These licenses are no longer active, so the project moves to Core and the notice says which of the three applies. Renew or add a new key, or contact support about a suspension. Your key stays stored, so you don't have to find it again to reactivate.

Short-lived instances no longer use an activation slot

Since October 8, the licensing service creates every new activation as pending. A pending activation doesn't count against your plan's activation limit, and the instance can restart and check in as often as it needs.

The pending window is currently 24 hours. After that, the environment's next check-in, from a scheduled refresh or a restart, makes the activation active. From then on it uses a slot, as before. Different environments each count separately, even when they serve the same project. Each activation is tied to the project ID stored in that environment's database and to its PUBLIC_URL, not to the license key alone. A restored database dump gets a new project ID when it activates, so it counts separately too. If all of your plan's activations are already in use by then, this environment can't get one. Admins see a warning that the license hit its activation limit, along with the date it stops working. After that date it moves to Core. To fix it, deactivate the license on an environment you no longer use.

A CI instance that's gone before its first check-in after 24 hours never leaves pending.

What that means in practice:

• A CI job that starts Directus, runs its tests and tears the instance down within a day doesn't take an activation.

• Staging, preview and other environments that run longer than 24 hours still use a slot once they check in again.

• Activations that were already active before October 8 are unchanged.

• This is a licensing service change, so it doesn't depend on which Directus version you run.

For developers: API and error changes

If you read license state from the API or catch license errors, 12.5 has breaking changes (release notes):

• /server/license no longer returns downgrade_reason. Read invalid_reason instead. It also reports why a license that's still in effect couldn't be renewed.

• /server/license now returns token_expires_at, the date the current license lapses if it isn't renewed.

• License request failures now return LICENSE_INVALID with a failure extension, or the standard FORBIDDEN, INVALID_PAYLOAD, REQUESTS_EXCEEDED and SERVICE_UNAVAILABLE errors.

• @directus/errors 3.0 drops LicenseManagedByEnvError, LicenseOfflineUnsupportedError, LicenseResolveIncompleteError and LicenseServiceUnavailableError.

• Activating a key while one is already stored now attempts to update it instead of throwing.

Get the update

The pending window is already live for every license. For everything else, upgrade self-hosted projects to Directus 12.6.0. 12.5.0 brings key retention and the warnings in Settings > License, and 12.6.0 adds the sidebar notices. If you integrate with the license API, review the breaking changes above first. Note that 12.6.0 also raises the minimum Node.js version to 26. Full details are in the 12.5.0 and 12.6.0 release notes.