docs: add troubleshooting for users who already belong to another account (#1042)

* docs: add troubleshooting for users who already belong to another account

Covers the 409 on invite and the 'user account ID mismatch' IdP sync
failure, how to free the user from the other account, and Sign-in
Domains as the way to prevent it. Links the new page from add users,
IdP sync, sign-in domains, account access, the troubleshooting hub and
the sidebar.

* docs: cover same-account 409s and recovery gaps on the user-in-another-account page

A 409 on invite also fires when the user is already in your own
account, for example waiting for approval, so the page now checks
Team -> Users first. Step 2a covers user approval and a domain that the
user's own account already holds, and Confirm it worked routes a
persisting 409 or failed sign-in to Support. Fixes the Identity
Provider Sync click path and drops the duplicate-users note, whose link
target had no such guidance.

* docs: scope account-conflict notes to Cloud and qualify the delete-account re-login note

Address CodeRabbit review: the 409 note on Add users and the IdP sync
rollout note now say they apply to NetBird Cloud, with the self-hosted
embedded IdP case pointing to Team -> Users. The delete-account page no
longer says a new account is always created on the next login: on
Cloud, a domain owned by another account (signup or verified sign-in
domain) joins that account instead.
This commit is contained in:
Bruno Mercier Costa
2026-10-16 09:15:25 +02:00
committed by GitHub
parent 3dcebe7b7c
commit 7a0e1e7b60
8 changed files with 129 additions and 5 deletions
+1 -1
View File
@@ -19,7 +19,7 @@ To delete your NetBird organization account, you must be a user with the [owner
After you delete your account, your session will end, and you will be redirected to the login page.
<Note>
If you log in again, a new account will be created.
If you log in again, a new account will be created. The exception on NetBird Cloud is an email domain that already belongs to another account, either as its signup domain or as a verified [sign-in domain](/manage/team/sign-in-domains). In that case you join that account instead, and may need an admin to approve you.
</Note>
## Get started
<div>
@@ -24,6 +24,8 @@ The domain can fall into one of the following categories - `public`, `private`,
The domains of the private category are the ones that are automatically grouped under the same account.
Public domains are the ones of the public email providers like Gmail.
Users on any other domain your organization uses, such as `company.co.uk` or a subsidiary's domain, don't join automatically. Add and verify those domains as [sign-in domains](/manage/team/sign-in-domains) so their users join your account too.
<Note>
It might happen (unlikely) that the domain classification system didn't classify your company's domain as private.
Our system was unsure about your domain and assigned an unclassified or public category to be on the safe side.
@@ -43,8 +45,9 @@ After logging in to the system, they will join your network automatically.
</p>
<Note>
If a user already has a NetBird account, you can't invite them.
This is a limitation that is likely to be removed in future versions.
On NetBird Cloud, you can't invite someone who already has a NetBird account, for example one they created by signing in before you invited them. The invite fails with a `409` error. See [User already belongs to another NetBird account](/help/troubleshooting-user-in-another-account) to move them into your account.
On self-hosted NetBird with the embedded identity provider, a `409` means the email address already belongs to a user in your account. Look for them under **Team → Users** instead.
</Note>
## Identity Provider (IdP) Sync
+4
View File
@@ -23,6 +23,10 @@ eliminating the need for manual grouping.
This feature is available in NetBird Cloud on the [Team plan](https://netbird.io/pricing) and above, and in self-hosted deployments with an [Enterprise Commercial License](/selfhosted/enterprise). The open source Community Edition does not include it.
</Note>
<Note>
**Before you roll out on NetBird Cloud**: IdP sync can't add a user who already belongs to another NetBird account, for example because they signed in early with an email domain your account doesn't know yet. Add every domain your users sign in with as a [sign-in domain](/manage/team/sign-in-domains) first. If a user still doesn't sync, see [User already belongs to another NetBird account](/help/troubleshooting-user-in-another-account).
</Note>
This video guide walks you through an example integration with Microsoft Entra ID, covering both user onboarding and
offboarding scenarios:
+1 -1
View File
@@ -25,7 +25,7 @@ You prove ownership of those domains, and everyone across your organization join
<Warning>
Verifying a domain does not move users who already have an account of their own. It decides where **new** users land, so add your domains before onboarding a team from another domain rather than after.
If someone turns out to have an earlier account they were not aware of, have them reach out to [NetBird Support](/help/netbird-support). The team verifies their identity and points them to whoever administers that account.
If someone already has an account of their own, inviting or syncing them fails. See [User already belongs to another NetBird account](/help/troubleshooting-user-in-another-account) to move them into yours. If they don't know where that account came from, have them reach out to [NetBird Support](/help/netbird-support). The team verifies their identity and points them to whoever administers that account.
</Warning>
## Add Domain