Account conflict resolution

When a signed-in user adds a credential — another email, phone, social account, or wallet — that already belongs to a different account, a conflict arises. The React SDK detected this inside the auth-flow modal and rendered every screen (account-exists, merge, per-field conflicts, wallet-already-used) automatically. The JavaScript SDK surfaces the same cases as typed errors and hands the UI to you.

What the React SDK did automatically

The widget pushed a built-in view for each conflict case. None of this was code you wrote — it happened inside the modal after a linking attempt.

React SDK built-in screen	What it handled
Account-exists prompt	”This credential already belongs to an account — merge or switch?”
Merge confirmation	Confirm the merge of the two accounts
Per-field conflict resolution	Resolve fields where the two accounts disagree
Same-email merge confirmation	Confirm a merge when both accounts share the same email
Wallet-already-used notice	”That wallet is already used by another account”

Merge completion and closing the modal happened automatically once the user confirmed.

What you own now

There is no modal and no automatic routing. The verification/linking call throws a typed error, and you branch on it to decide which UI to show.

React SDK (automatic)	JavaScript SDK (you call)
Account-exists / merge prompt	catch `MergeAccountsConfirmationError`, then render your confirm UI
Per-field conflict resolution	read `error.mergeConflicts`, collect one `MergeUserConflictResolution` per field
Automatic merge completion	`mergeUserAccounts({ conflictResolutions })` / `useMergeUserAccounts()`
Wallet-already-used notice	catch `WalletAlreadyLinkedToAnotherUserError`

Errors you now own

The linking calls (verifyOTP, the social verification flow, connectAndVerifyWithWalletProvider / verifyWalletAccount) throw one of these when the credential belongs to someone else:

Error	Meaning	Recoverable
`MergeAccountsConfirmationError`	The two accounts can be merged; carries `mergeConflicts`	Yes — complete with `mergeUserAccounts()`
`WalletAlreadyLinkedToAnotherUserError`	The wallet is verified on another account and can’t be moved	No
`LinkCredentialError`	The credential can’t be reassigned or merged	No

import {
  verifyWalletAccount,
  mergeUserAccounts,
  MergeAccountsConfirmationError,
  WalletAlreadyLinkedToAnotherUserError,
  LinkCredentialError,
} from '@dynamic-labs-sdk/client';

try {
  await verifyWalletAccount({ walletAccount });
} catch (error) {
  if (error instanceof MergeAccountsConfirmationError) {
    // resolveConflicts is your own UI: prompt the user to pick a value for
    // each conflicting field, returning MergeUserConflictResolution[].
    await mergeUserAccounts(
      error.mergeConflicts
        ? { conflictResolutions: resolveConflicts(error.mergeConflicts) }
        : undefined,
    );
  } else if (error instanceof WalletAlreadyLinkedToAnotherUserError) {
    showWalletAlreadyUsed();
  } else if (error instanceof LinkCredentialError) {
    showCannotReassign();
  } else {
    throw error;
  }
}

mergeUserAccounts() persists the merged session internally and returns the merged user — you don’t re-authenticate afterward. Call it with no arguments when there are no conflicts, or with one resolution per conflicting field.

Completing the merge

Once the user has confirmed (and resolved any per-field conflicts), complete the merge. In React, useMergeUserAccounts() is a mutation whose resolved data is the merged user.

TypeScript
React

import { mergeUserAccounts } from '@dynamic-labs-sdk/client';

const mergedUser = await mergeUserAccounts({ conflictResolutions });

import { useMergeUserAccounts } from '@dynamic-labs-sdk/react-hooks';

const { mutateAsync: mergeAccounts, isPending } = useMergeUserAccounts();

const mergedUser = await mergeAccounts({ conflictResolutions });

The full walkthrough — building the confirm dialog, the per-field conflict picker, and the wallet-already-used state — is in the Building UI guides.

Installation & Configuration

React Native

Building UI

Migrating from React

Chains & Networks

Authenticate

User & Session Management

Wallets

Flow

Swaps

Funding & Onramp

Events

Account conflict resolution

What the React SDK did automatically

What you own now

Errors you now own

Completing the merge

See also

​What the React SDK did automatically

​What you own now

​Errors you now own

​Completing the merge

​See also

What the React SDK did automatically

What you own now

Errors you now own

Completing the merge

See also