mintlify · ethanpalm · Aug 8, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 8, 2026
diff --git a/cli/commands.mdx b/cli/commands.mdx
@@ -85,15 +85,15 @@

 Windsurf has a global MCP configuration only. With `--project`, the command still writes the MCP entry to the global Windsurf configuration and writes the usage rule in the current project.

 Rerunning the command updates an existing `mintlify-index` entry and its generated rule. The command preserves unrelated configuration. If an existing JSON or JSONC configuration is invalid, the command reports an error without changing that file.

 Supported clients and their standard configuration files include:

 | Client | Global configuration | Project configuration |
 | --- | --- | --- |
 | Claude Code | `~/.claude.json` | `.mcp.json` |
 | Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
 | VS Code | User `mcp.json` | `.vscode/mcp.json` |
 | Codex | `~/.codex/config.toml` | `.codex/config.toml` |
 | OpenCode | `~/.config/opencode/opencode.json` | `opencode.json` |
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` | Global only |
@@ -202,6 +202,8 @@
 
 Add the `TXT` records first, then add the `CNAME` once the verification records validate. See [Custom domain](/customize/custom-domain) for full DNS setup instructions, apex domain requirements, and TLS provisioning details.
 
+If the command fails with `Domain is already in use by another deployment in your organization` or `Domain is already claimed by another organization`, the domain is bound to another Mintlify deployment. See [Add domain fails with "Domain is already claimed by another organization"](/help-center/domain-already-claimed-by-another-organization) to release it and re-add it.
+
 <Note>
   If some `TXT` records are still generating when the command exits, check the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard for the remaining values.
 </Note>
@@ -364,7 +366,7 @@
 | `--check-redirects` | Also check that redirect destinations in `docs.json` resolve to valid paths. |
 | `--check-snippets` | Also check links inside `<Snippet>` components. |

 Pass `--files` to limit the check to specific pages. This is useful for validating a single page you just edited or scoping checks to a directory in CI. When `--files` is set with `--check-external`, only external URLs on the selected pages are fetched.

 ```bash
 # Check a specific page
@@ -544,13 +546,13 @@
 mint format
 ```

 Run the command from the root of your docs project. It walks every subdirectory, skipping paths matched by `.gitignore` and any Mintlify ignore rules. Files that already match the canonical output are left untouched.

 <Warning>
  `mint format` rewrites files in place. Commit or stash your changes before running it so you can review the diff.
 </Warning>

 When it finishes, the command prints how many MDX files were reformatted and how many failed to parse. If any file fails, the command exits with code `1` and prints the file path and error, so you can run it in CI to enforce consistent formatting.

 ---


diff --git a/customize/custom-domain.mdx b/customize/custom-domain.mdx
@@ -144,6 +144,8 @@ Only retry validation after you confirm that your DNS records are correct. Repea
 
 To remove a custom domain, click the <Icon name="trash-2" /> remove icon next to your domain on the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page and confirm the removal. Existing links to the domain may break, and re-adding the domain may require reconfiguring your DNS records.
 
+Removing a domain also releases it so another Mintlify deployment or organization can claim it. If you cannot add a domain because another deployment holds it, see [Add domain fails with "Domain is already claimed by another organization"](/help-center/domain-already-claimed-by-another-organization).
+
 ## Set a canonical URL
 
 After configuring your DNS, set a canonical URL to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content.

diff --git a/docs.json b/docs.json
@@ -459,7 +459,8 @@
               {
                 "group": "Help center",
                 "pages": [
-                  "help-center/openapi-url-fetch-fails-during-build"
+                  "help-center/openapi-url-fetch-fails-during-build",
+                  "help-center/domain-already-claimed-by-another-organization"
                 ]
               }
             ]

diff --git a/help-center/domain-already-claimed-by-another-organization.mdx b/help-center/domain-already-claimed-by-another-organization.mdx
@@ -0,0 +1,36 @@
+---
+title: "Add domain fails with \"Domain is already claimed by another organization\""
+description: "Release a custom domain from another Mintlify deployment or request help when adding it fails because another deployment or organization already holds it."
+keywords: ["Domain is already in use by another deployment in your organization", "Domain is already claimed by another organization", "custom domain", "release domain", "domain ownership"]
+---
+
+When you try to add a custom domain that is registered to another Mintlify deployment, the dashboard or [`mint add-domain`](/cli/commands#mint-add-domain) returns one of these errors:
+
+- `Domain is already in use by another deployment in your organization` means the domain belongs to another deployment you can access.
+- `Domain is already claimed by another organization` means the domain belongs to a deployment in a different Mintlify organization. This can happen when a trial account, unused organization, or deployment created with another work email still holds the domain.
+
+Only one deployment can hold a custom domain at a time. Release the domain from the current deployment before you add it to the destination deployment.
+
+## Release the domain yourself
+
+If you can access the organization that holds the domain:
+
+1. Sign in to the [dashboard](https://app.mintlify.com/) and switch to the organization that holds the domain.
+2. Open the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page for the deployment that holds the domain.
+3. Click the <Icon name="trash-2" /> remove icon next to the domain and confirm the removal.
+4. Switch to the destination organization and add the domain from its [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page.
+
+Your DNS records remain valid as long as the `CNAME` still points to `cname.mintlify.builders`. If you also want to retire the old deployment, delete it from the [Danger zone](https://app.mintlify.com/settings/organization/danger-zone). See [Delete a deployment](/deploy/deployments#delete-a-deployment).
+
+## Request a release from support
+
+If you cannot access the organization that holds the domain, email <a href="mailto:support@mintlify.com">support@mintlify.com</a> with proof that you own it. This can happen when the organization belongs to a former employee, uses a personal email you no longer access, or was abandoned without releasing the domain.
+
+Include:
+
+- The custom domain, like `docs.example.com`.
+- The destination organization and deployment where you want to add it, formatted as `app.mintlify.com/<your-org>/<your-deployment>`.
+- Any email addresses or organization names that might hold the domain.
+- Proof that you control the domain, such as a screenshot from your DNS provider's admin console. Support may instead ask you to add a verification `TXT` record.
+
+After support releases the domain, add it from the dashboard or with [`mint add-domain`](/cli/commands#mint-add-domain).