From 7a0e1e7b60d0e8a9c3cd3ca29e9778b7d3ea8dee Mon Sep 17 00:00:00 2001 From: Bruno Mercier Costa <94469565+emrcbrn@users.noreply.github.com> Date: Fri, 16 Oct 2026 09:15:25 +0200 Subject: [PATCH] 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. --- src/components/NavigationDocs.jsx | 4 + .../help/troubleshooting-account-access.mdx | 2 +- ...roubleshooting-user-in-another-account.mdx | 111 ++++++++++++++++++ src/pages/help/troubleshooting.mdx | 2 + src/pages/manage/settings/delete-account.mdx | 2 +- .../manage/team/add-users-to-your-network.mdx | 7 +- src/pages/manage/team/idp-sync/index.mdx | 4 + src/pages/manage/team/sign-in-domains.mdx | 2 +- 8 files changed, 129 insertions(+), 5 deletions(-) create mode 100644 src/pages/help/troubleshooting-user-in-another-account.mdx diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 3e9e418d..84c5dcb1 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -1141,6 +1141,10 @@ export const docsNavigation = [ title: 'Pending approval', href: '/help/troubleshooting-account-access', }, + { + title: 'User in another account', + href: '/help/troubleshooting-user-in-another-account', + }, { title: 'IdP & SSO setup', href: '/manage/team/single-sign-on' }, { title: 'User provisioning', href: '/manage/team/idp-sync' }, { diff --git a/src/pages/help/troubleshooting-account-access.mdx b/src/pages/help/troubleshooting-account-access.mdx index ab52d3bb..8b42a0d1 100644 --- a/src/pages/help/troubleshooting-account-access.mdx +++ b/src/pages/help/troubleshooting-account-access.mdx @@ -54,7 +54,7 @@ The **Sign-in Domains** section only appears once your account's own domain is c To confirm the cause, ask your teammate which email address they signed in with, and check its domain against the Sign-in Domains list. -Verifying a domain does not move a teammate who already has an account of their own: it only changes where new sign-ins land. For a teammate already in a separate account, contact [NetBird Support](/help/netbird-support). +Verifying a domain does not move a teammate who already has an account of their own: it only changes where new sign-ins land, and inviting or syncing them fails until they leave that account. For a teammate already in a separate account, see [User already belongs to another NetBird account](/help/troubleshooting-user-in-another-account). If your account requires user approval, a teammate who joins through domain matching is held for approval. That is the [Waiting for Approval](#what-the-waiting-for-approval-screen-tells-you) screen above, and an admin approves them as described in [What to do](#what-to-do). diff --git a/src/pages/help/troubleshooting-user-in-another-account.mdx b/src/pages/help/troubleshooting-user-in-another-account.mdx new file mode 100644 index 00000000..c7e71c50 --- /dev/null +++ b/src/pages/help/troubleshooting-user-in-another-account.mdx @@ -0,0 +1,111 @@ +import {Warning} from "@/components/mdx"; + +export const description = "Why NetBird refuses to invite or sync a user who already has a NetBird account elsewhere, how to move them into your account, and how Sign-in Domains stops it happening again." + +# User Already Belongs to Another NetBird Account + +You try to add someone to your NetBird account and it doesn't work: the invite fails with a `409` error, or Identity Provider Sync never adds them, even though they are in the right group in your identity provider (IdP). + +In almost every case, the person already signed in to NetBird before you added them, and that sign-in put them in a **different NetBird account**. A NetBird user belongs to exactly one account, so NetBird won't copy or move them into yours. You have to free the user from the other account first. + +This page is for NetBird Cloud, where many organizations share one service. On self-hosted NetBird, see [Self-hosted](#self-hosted) at the end. + +## Symptoms + +You see one of these: + +- **Invite fails with 409.** Inviting the user from **Team → Users → Invite User** shows `Code 409: Can't invite a user with an existing NetBird account`. +- **IdP sync skips the user.** The user is assigned to NetBird in your IdP, other users sync fine, but this one never appears under **Team → Users**. Your IdP's provisioning log may show the user as provisioned successfully, because NetBird accepts the record first and adds users to your account in a later step. That later step is where it fails, and the integration's sync log records: + + ```text + failed to sync new users: failed to process update for user : user account ID mismatch + ``` + + The dashboard shows only when the integration last synced, not the log itself. To read the log, call the sync logs endpoint for your integration in the API: [Entra ID (API)](/ipa/resources/idp-azure-integrations#get-azure-integration-sync-logs), [Google Workspace](/ipa/resources/idp-google-integrations#get-google-integration-sync-logs), [Okta](/ipa/resources/idp-okta-scim-integrations#get-okta-scim-integration-sync-logs), or [the SCIM-based integrations](/ipa/resources/idp-scim-integrations#get-scim-integration-sync-logs). + +Both errors usually mean the same thing: NetBird already knows this person, and they belong to another account. Rule out the simpler case below first. + +## Check your own account first + +An invite also fails with `409` when the person is already a user in **your** account. For example, they signed in on their own and joined through their email domain, or they are waiting for approval. Look for their email address under **Team → Users**, including users waiting for approval. If they are there, don't invite them again: [approve them](/manage/team/approve-users#approve-or-reject-user), or change their role if they need dashboard access. + +## Why the user ended up in another account + +When someone signs in to NetBird for the first time, NetBird decides which account they join from their email domain. They join your account only if the domain is one your account owns. Otherwise NetBird creates a new account with them as its Owner. Ordered by how often we see them: + +1. **Their email domain isn't your signup domain.** You signed up as `admin@company.com`, and the user signed in as `jane@company.co.uk`, a subsidiary, or a second brand. NetBird doesn't know `company.co.uk` belongs to you, so Jane got an account of her own. This is the case [Sign-in Domains](/manage/team/sign-in-domains) solves. +2. **They signed in before your rollout.** They tried NetBird early, or opened the dashboard link before you set up IdP sync or invited them. If their domain was one you hadn't added yet, they landed in an account of their own, as in case 1. +3. **They are a member of another organization's account.** For example, a partner or customer account, a former employer's account, or a test account someone created. +4. **Their domain isn't recognized as a business domain.** NetBird treats public email providers like Gmail as personal, and every user on them gets their own account. Rarely, a company domain is classified this way too. [NetBird Support](/help/netbird-support) can correct the classification. + +## Fix it + +### 1. Find out which account the user is in + +Ask the user to sign in at [app.netbird.io](https://app.netbird.io) with the same email address you are adding, and look at what they see: + +- **A network with only their own devices, and the Settings → Danger zone tab is available, not greyed out.** Only an Owner can open it, so they are the Owner of an account of their own (cases 1, 2, or 4). Go to [step 2a](#2a-the-user-owns-an-account-of-their-own). +- **Someone else's network, or a Waiting for Approval screen naming another organization.** They are a member of another account (case 3). Go to [step 2b](#2b-the-user-is-a-member-of-another-organizations-account). +- **A Waiting for Approval screen naming your own domain.** They are already in your account. See [Check your own account first](#check-your-own-account-first). + +If neither fits, or the user doesn't know where the account came from, contact [NetBird Support](/help/netbird-support). The team verifies the user's identity and points them to whoever administers that account. + +### 2a. The user owns an account of their own + + + Deleting an account permanently deletes everything in it: its peers, groups, policies, setup keys, and any other users. Before the user deletes it, confirm it holds nothing they still need, and that no one else relies on it. + + +1. **If their domain differs from yours, add it as a sign-in domain first.** In your account, go to **Settings → Authentication → Sign-in Domains** and add and verify their domain, for example `company.co.uk`. See [Sign-in Domains](/manage/team/sign-in-domains). Skip this step if they share your domain. +2. **Have the user delete their account.** In their account, they go to **Settings → Danger zone** and click **Delete Account**. See [Delete your account](/manage/settings/delete-account). +3. **Bring them into your account.** If you verified their domain in step 1, or they share your domain, their next sign-in joins your account, and IdP sync attaches their groups on its next run. If you don't use either, invite them again or run the sync. If your account requires [user approval](/manage/team/approve-users#approve-or-reject-user), approve them under **Team → Users**. + +Doing step 1 before step 2 matters. Without a matching domain, a user who signs in again before your next sync gets a fresh account of their own, and you are back where you started. + +If verification in step 1 fails, the user's own account may already hold that domain. Only one account can verify a domain, so do step 2 first, then verify the domain right away. Ask the user not to sign in again until the domain shows as verified. + +### 2b. The user is a member of another organization's account + +Only that account's admins can release the user. Ask them to delete the user from **Team → Users** in their account. Removing a user also removes the peers registered under them in that account. + +Once the user is removed, invite them again, or let IdP sync pick them up on its next run. + +### 3. Run the sync or the invite again + +- **Direct invite.** Invite the user again from **Team → Users**. +- **Entra ID (API) and Google Workspace.** Open the integration under **Integrations → Identity Provider Sync** and force a synchronization, or wait for the next scheduled one. +- **SCIM integrations** (Entra ID (SCIM), Okta, JumpCloud, Keycloak, IIJ ID, generic SCIM). Your IdP pushes changes on its own schedule. Trigger provisioning for the user in your IdP, for example **Provision on demand** in Entra ID, or wait for the next cycle. + +## Confirm it worked + +The user appears under **Team → Users** in your account, with the groups from your IdP, and the next sync log no longer reports `user account ID mismatch` for them. When the user signs in at [app.netbird.io](https://app.netbird.io), they see your network, or a Waiting for Approval screen naming your own domain if your account requires user approval. + +If the invite still fails with `409`, or the user can't sign in after their old account is gone, contact [NetBird Support](/help/netbird-support) with their email address. + +## Prevent it + +Most of these conflicts come from case 1: an organization uses more than one email domain and only the signup domain is known to NetBird. + +- **Add every domain your organization uses as a [sign-in domain](/manage/team/sign-in-domains), before you roll NetBird out.** Sign-in domains decide where new users land, so a verified domain sends every first sign-in on it to your account. They don't move users who already have an account elsewhere, which is why adding them first matters. +- **Set up IdP sync and sign-in domains before you announce NetBird to users.** Anyone who signs in early, on a domain you haven't added yet, gets an account of their own. + +## Self-hosted + +A self-hosted NetBird deployment runs one account by default, and every user joins it. A user can't be stuck in another account, so `user account ID mismatch` doesn't apply. + +With the embedded identity provider, a `409` on invite means the email address already belongs to a user in your own account. Look for them under **Team → Users** instead of inviting them again. + +## Recap + +- One NetBird user belongs to exactly one account. A `409` on invite, or `user account ID mismatch` in the sync log, usually means the user is already in another one. Check **Team → Users** in your own account first. +- Usually they signed in early, with an email domain your account didn't know yet. +- Free the user first: they delete their own account, or the other account's admins remove them. Then invite or sync again. +- Add and verify every domain you use as a sign-in domain before rollout, so first sign-ins land in your account. + +## Related docs + +- [Allow users from other domains to join your account](/manage/team/sign-in-domains) +- [Add users to your network](/manage/team/add-users-to-your-network) +- [Provision users and groups from your identity provider](/manage/team/idp-sync) +- [Pending approval and account invitations](/help/troubleshooting-account-access) +- [Delete your account](/manage/settings/delete-account) diff --git a/src/pages/help/troubleshooting.mdx b/src/pages/help/troubleshooting.mdx index 2e0ab167..cc6ca28e 100644 --- a/src/pages/help/troubleshooting.mdx +++ b/src/pages/help/troubleshooting.mdx @@ -17,6 +17,7 @@ The problems support sees most often. | Symptom | Start here | |---|---| | The dashboard shows **Waiting for Approval** after you sign in | [Pending approval and account invitations](/help/troubleshooting-account-access) | +| Inviting a user fails with `409`, or IdP sync never adds them | [User already belongs to another NetBird account](/help/troubleshooting-user-in-another-account) | | The client keeps asking you to log in again, or a peer shows `Login required` | [Peer session expiration](/manage/settings/enforce-periodic-user-authentication) | | A peer shows `Relayed` instead of `P2P` | [Troubleshooting relayed connections](/help/troubleshooting-relayed-connections) | | The tunnel works but is slow, or takes long to connect | [Troubleshooting performance](/help/troubleshooting-performance) | @@ -98,6 +99,7 @@ The problems support sees most often. chips: [ { label: "Pending approval", href: "/help/troubleshooting-account-access" }, { label: "Teammate got their own account", href: "/help/troubleshooting-account-access#a-teammate-got-their-own-account" }, + { label: "Can't invite or sync a user", href: "/help/troubleshooting-user-in-another-account" }, { label: "Sign-in domains", href: "/manage/team/sign-in-domains" }, { label: "Session expiration", href: "/manage/settings/enforce-periodic-user-authentication" }, { label: "SSO setup guides", href: "/manage/team/single-sign-on" }, diff --git a/src/pages/manage/settings/delete-account.mdx b/src/pages/manage/settings/delete-account.mdx index a5001940..e63e0143 100644 --- a/src/pages/manage/settings/delete-account.mdx +++ b/src/pages/manage/settings/delete-account.mdx @@ -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. - 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. ## Get started
diff --git a/src/pages/manage/team/add-users-to-your-network.mdx b/src/pages/manage/team/add-users-to-your-network.mdx index b4615b2f..b8ca19d1 100644 --- a/src/pages/manage/team/add-users-to-your-network.mdx +++ b/src/pages/manage/team/add-users-to-your-network.mdx @@ -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. + 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.

- 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. ## Identity Provider (IdP) Sync diff --git a/src/pages/manage/team/idp-sync/index.mdx b/src/pages/manage/team/idp-sync/index.mdx index 7483e958..af7765f5 100644 --- a/src/pages/manage/team/idp-sync/index.mdx +++ b/src/pages/manage/team/idp-sync/index.mdx @@ -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. + + **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). + + This video guide walks you through an example integration with Microsoft Entra ID, covering both user onboarding and offboarding scenarios: diff --git a/src/pages/manage/team/sign-in-domains.mdx b/src/pages/manage/team/sign-in-domains.mdx index 66580030..faa24739 100644 --- a/src/pages/manage/team/sign-in-domains.mdx +++ b/src/pages/manage/team/sign-in-domains.mdx @@ -25,7 +25,7 @@ You prove ownership of those domains, and everyone across your organization join 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. ## Add Domain