Add Shared Databases Across Environments to Licensing

content/licensing/1.overview.md

@@ -156,6 +156,8 @@ A license binds to your project and `PUBLIC_URL`, not to a container, IP address
 
 Set the license through the `LICENSE_KEY` (or `LICENSE_TOKEN`) environment variable at the service or task level so that every replica inherits the same value automatically. New containers spun up by autoscaling pick up the license on start without any manual setup or per-container retrieval.
 
+Using a different `LICENSE_KEY` per environment against a shared database causes the environments' bindings to conflict. See [Troubleshooting](#troubleshooting) below.
+
 ## Resolution Flow
 
 If your instance exceeds its entitlements — for example, after downgrading a plan — the Studio surfaces a **Resource Resolution** screen for admins. This screen lists each entitlement that requires action:
@@ -194,3 +196,22 @@ When an existing instance upgrades to Directus 12 without a license, behavior de
 - **Above core tier limits** — the instance enters a 30-day grace period during which it continues to function normally. Admins see a reminder on every login. Add a license key to clear the reminder, or reduce usage to within core limits before the grace period ends.
 
 If the grace period ends with usage still above core limits, the resolution flow is triggered on next admin login.
+
+## Troubleshooting
+
+### Binding conflicts across shared-database environments
+
+If environments that share a database are configured with **different** `LICENSE_KEY` values, whichever environment starts second tries to rebind the shared project to its own key and `PUBLIC_URL`. The licensing service rejects this, and that environment fails to start with a binding error.
+
+To recover:
+
+1. On the environment with the working license, remove `LICENSE_KEY` from the environment and restart. This unlocks the Studio license editor.
+2. Go to **Settings > License** and click **Deactivate License**. This releases the binding on the licensing service, rather than just clearing it locally.
+3. Stop that environment.
+4. Start the other environment. With no license data left in the database, it activates fresh.
+
+::callout{icon="i-lucide-triangle-alert" color="warning"}
+Don't clear `license_key` directly in the database to work around a binding conflict. This leaves the old activation stranded on the licensing service, still counted against your activation limit. Always deactivate through the Studio or API first.
+::
+
+Going forward, use the same `LICENSE_KEY` across all environments sharing that database — see [Activations and Project Bindings](#activations-and-project-bindings).