Wagmi SDK — Troubleshooting

Common issues and solutions when integrating CROSSx with wagmi.

useAccount() shows disconnected after page refresh

Symptom: SDK initialization succeeds (session is restored, address is loaded), but useAccount() still returns isConnected: false after a page refresh.

Cause: wagmi calls connector.setup() internally without await (fire-and-forget). If setup() has not finished SDK initialization by the time wagmi calls isAuthorized(), it returns false and wagmi skips reconnection.

Timeline (race condition):

1. wagmi: connector.setup()         → fires sdk.initialize() (async, in progress)
2. wagmi: await isAuthorized()      → sdk.isAuthenticated() → false ❌ (init not done)
3. wagmi: skip reconnect            → useAccount() = disconnected
4. SDK: initialize() completes      → too late, wagmi already gave up

Solution (SDK v1.2.5+): This is resolved at the SDK level. The connector's isAuthorized() now awaits sdk.whenReady() before checking authentication state:

// Connector internals (automatic, no action needed)
async isAuthorized() {
  await sdk.whenReady()          // waits for initialize() to complete
  return sdk.isAuthenticated()   // now returns the correct value
}

Action required: Update to @nexus-cross/crossx-sdk-wagmi v1.2.5 or later. No code changes needed in your DApp.

If you were using a SdkReconnectGuard workaround, you can safely remove it after upgrading.

For SDK versions before v1.2.5

If you cannot upgrade immediately, use this workaround component:

import { useEffect } from 'react'
import { useAccount } from 'wagmi'
import { reconnect } from 'wagmi/actions'
import { wagmiConfig } from './wagmi.config'

function SdkReconnectGuard({ sdk }: { sdk: CROSSxSDK }) {
  const { status } = useAccount()

  useEffect(() => {
    if (status !== 'disconnected') return

    if (sdk.isAuthenticated()) {
      reconnect(wagmiConfig)
      return
    }

    const unsubscribe = sdk.on('initialized', ({ restored }) => {
      if (restored) reconnect(wagmiConfig)
    })
    return unsubscribe
  }, [status])

  return null
}

Place it inside your WagmiProvider:

<WagmiProvider config={wagmiConfig}>
  <QueryClientProvider client={queryClient}>
    <SdkReconnectGuard sdk={sdk} />
    <App />
  </QueryClientProvider>
</WagmiProvider>

Already logged in. Call signOut() first. error on reconnect

Symptom: After refresh, the app throws an error instead of restoring the session.

Cause: The connector attempted signInWithCreate() when the SDK was already authenticated but had no cached addresses.

Solution: This is handled automatically in the connector. On reconnect, it first tries sdk.getAddresses() to recover wallet info. Only if that returns empty does it sign out and start a fresh login.

If you see this error, ensure:

1. You are using the latest @nexus-cross/crossx-sdk-wagmi package
2. You are not calling sdk.signIn() manually while the connector is managing the session

Password modal appears on every page refresh

Symptom: The password prompt shows up each time the page is refreshed, even though the user already entered it.

Cause: The SDK's loadWalletAfterAuth() requires password verification to decrypt wallet keys. This is expected security behavior on the first load after refresh.

Solution: This is by design — the SDK verifies the wallet password once per session for security. The password is held in memory for the session duration and cleared on signOut() or page unload.

Wrong wallet address shown after refresh

Symptom: User selected wallet index 1, but after refresh, wallet index 0 is shown.

Cause: The selected wallet index was not persisted.

Solution: The connector automatically persists the wallet index in localStorage (key: crossx-wallet-index). Ensure:

1. localStorage is available in your environment
2. If using SSR (e.g. Next.js), provide custom callbacks:

crossxConnector({
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
  getStoredWalletIndex: () => {
    // read from cookies or other SSR-safe storage
    return Number(getCookie('crossx-wallet-index')) || 0
  },
  onWalletIndexChanged: (index) => {
    setCookie('crossx-wallet-index', String(index))
  },
})

Connector not found in useConnect()

Symptom: connectors.find(c => c.id === 'crossx') returns undefined.

Cause: The connector was not added to the wagmi config.

Solution: Verify your createConfig call includes the CROSSx connector:

import { createConfig, http } from 'wagmi'
import { crossxConnector } from '@nexus-cross/crossx-sdk-wagmi'

export const wagmiConfig = createConfig({
  connectors: [
    crossxConnector({
      projectId: 'YOUR_PROJECT_ID',
      appName: 'My DApp',
    }),
  ],
  chains: [crossMainnet],
  transports: { [crossMainnet.id]: http() },
})

Chain XXXXX is not configured error on switchChain

Symptom: Calling useSwitchChain throws Chain XXXXX is not configured.

Cause: The target chain is not included in the wagmi chains array.

Solution: Add all chains you need to both chains and transports:

export const wagmiConfig = createConfig({
  connectors: [crossxConnector({ projectId: '...', appName: '...' })],
  chains: [crossMainnet, crossTestnet],   // ← include both
  transports: {
    [crossMainnet.id]: http(),
    [crossTestnet.id]: http(),            // ← transport for each chain
  },
})

Related

• Getting Started
• Authentication
• API Reference
• Core SDK API Reference