From 223c2fb200f5e3a9bd9b011443b4df45a3dbb213 Mon Sep 17 00:00:00 2001 From: James White Date: Tue, 11 Aug 2026 22:22:21 +0100 Subject: [PATCH 1/2] Document license re-activation when moving an instance to a new URL Changing PUBLIC_URL does not rebind the existing license activation. Revalidation then fails silently until the cached license expires, at which point the instance downgrades to core and can lock down. Add explicit migration steps and a warning callout covering this. Co-Authored-By: Claude Fable 5 --- content/licensing/1.overview.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/content/licensing/1.overview.md b/content/licensing/1.overview.md index 69e011be..041d7c26 100644 --- a/content/licensing/1.overview.md +++ b/content/licensing/1.overview.md @@ -66,13 +66,14 @@ If `PUBLIC_URL` is not set, Directus will still start successfully with a warnin Attempts to add a license key during setup will grant access to the Studio, but license activation will fail and an error will be logged. Likewise, adding or managing a license through **Settings → License** will fail and display the following error: - ``` [INVALID_PAYLOAD] Invalid payload. public_url must be a valid absolute URL. ``` If you encounter this error, configure `PUBLIC_URL` with a qualified URL, restart Directus, and then re-apply the license. +If you change `PUBLIC_URL` after activation, you must re-apply your license so it binds to the new URL. See [Moving an Instance to a New URL](#moving-an-instance-to-a-new-url) for the steps and the consequences of skipping them. + ::callout{icon="i-lucide-info" color="info"} In addition to licensing, `PUBLIC_URL` is used throughout Directus for features such as OAuth redirects, password reset emails, and other public-facing links. For more information, see the [`PUBLIC_URL` entry in the general configuration reference](/configuration/general). :: @@ -188,9 +189,17 @@ If your current usage is above core tier limits when you deactivate, the Studio ### Moving an Instance to a New URL -If you change the `PUBLIC_URL` of an existing instance — for example, when migrating to a new domain — the license key will register a new activation against the new URL. The previous activation against the old URL remains in place until you deactivate it. +A license activation is bound to the `PUBLIC_URL` value at the time it is created. Changing the `PUBLIC_URL` of an existing instance, such as when migrating to a new domain, does not update the binding automatically. + +To move an instance to a new URL: -To reuse the same license on the new URL without exceeding your license's activation limit, deactivate the license on the old instance **before** bringing the new one online. +1. Deactivate the license while `PUBLIC_URL` still holds its old value. This frees the old activation so it does not count against your activation limit. See [Deactivating a License](#deactivating-a-license). +2. Update `PUBLIC_URL` and restart Directus. +3. Re-apply your license key. This registers a new activation against the new URL. + +::callout{icon="i-lucide-triangle-alert" color="warning"} +**Changing `PUBLIC_URL` without re-applying your license eventually downgrades the instance to the core tier.** Once the URL no longer matches its activation, periodic revalidation fails silently and the instance continues to run on its cached license. When the cached license expires, the downgrade takes effect without warning. If usage is above core tier limits at that point, the instance becomes [locked down](#locked-down-instances) and the API returns errors until the license is resolved. Your data is unaffected, and re-applying the license key restores normal operation immediately. +:: ### Replicas and Horizontal Scaling From 77698bbf218309c63a757060eb08df65440d4f4e Mon Sep 17 00:00:00 2001 From: James White Date: Tue, 11 Aug 2026 22:46:20 +0100 Subject: [PATCH 2/2] add license clarifications --- content/licensing/1.overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/licensing/1.overview.md b/content/licensing/1.overview.md index 041d7c26..a525d3c0 100644 --- a/content/licensing/1.overview.md +++ b/content/licensing/1.overview.md @@ -198,7 +198,7 @@ To move an instance to a new URL: 3. Re-apply your license key. This registers a new activation against the new URL. ::callout{icon="i-lucide-triangle-alert" color="warning"} -**Changing `PUBLIC_URL` without re-applying your license eventually downgrades the instance to the core tier.** Once the URL no longer matches its activation, periodic revalidation fails silently and the instance continues to run on its cached license. When the cached license expires, the downgrade takes effect without warning. If usage is above core tier limits at that point, the instance becomes [locked down](#locked-down-instances) and the API returns errors until the license is resolved. Your data is unaffected, and re-applying the license key restores normal operation immediately. +**Changing `PUBLIC_URL` without re-applying your license eventually downgrades the instance to the core tier.** Once the URL no longer matches its activation, periodic revalidation fails and the instance continues to run on its cached license. When the cached license expires, the downgrade takes effect without warning. If usage is above core tier limits at that point, the instance becomes [locked down](#locked-down-instances) and the API returns errors until the license is resolved. Your data is unaffected, and re-applying the license key restores normal operation immediately. :: ### Replicas and Horizontal Scaling