Troubleshooting

This page covers the issues most likely to appear when integrating the DogeOS SDK.

Provider and Rendering

Hooks throw “must be used within WalletConnectProvider”

useWalletConnect(), useAccount(), and useConnectors() read SDK context. The component calling the hook must render under WalletConnectProvider.


<WalletConnectProvider config={{ clientId: "YOUR_DOGEOS_CLIENT_ID" }}>
  <YourWalletComponent />
</WalletConnectProvider>

Nothing renders in Next.js

WalletConnectProvider is browser-only. In Next.js, put it in a client component.


"use client"
 
import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WalletConnectProvider config={{ clientId: process.env.NEXT_PUBLIC_DOGEOS_CLIENT_ID! }}>
      {children}
    </WalletConnectProvider>
  )
}

Import the SDK stylesheet once.


import "@dogeos/dogeos-sdk/style.css"

CSS Conflicts

App styles override SDK controls

The SDK ships its own stylesheet and Tomo UI theme tokens. If buttons, inputs, icons, spacing, or colors look wrong inside the connect modal:

Confirm @dogeos/dogeos-sdk/style.css is imported once before the provider renders.
Prefer theme config for brand colors instead of targeting SDK-generated class names.
Scope app resets to your own app shell instead of global selectors such as button, input, svg, img, or *.
If a temporary CSS override is unavoidable, put it after the SDK stylesheet and keep the selector scoped to your integration wrapper.

Render WalletConnectProvider near the app root, outside containers that use overflow: hidden, transforms, or isolated stacking contexts. The provider creates an internal #modal-container, so apps with a custom z-index scale can reserve a high layer for it.


#modal-container {
  position: relative;
  z-index: 9999;
}

Embedded wallet sizing conflicts

Use the wrapper props on WalletConnectEmbed for layout adjustments.


<WalletConnectEmbed style={{ width: "100%", maxWidth: 448 }} />

Avoid relying on SDK internal class names for embedded wallet styling; they can change between SDK releases.

Dark mode does not match the app

Pass the current app mode through theme.defaultTheme and update the provider config when your app theme changes. This keeps the modal and embedded wallet aligned with the surrounding UI.

Client ID

`clientId` is missing

clientId is required by WalletConnectKitConfig, and embedded wallet initialization passes it to the DogeOS embedded wallet service. Request a value through the Partner Interest Form .


const dogeConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
}

If you use environment variables, make sure the variable is exposed to the browser. In Next.js App Router that usually means NEXT_PUBLIC_DOGEOS_CLIENT_ID.

Connections

No wallets appear

Check the provider config:

clientId is set.
chains includes the chain families you want to support.
If you pass connectors, it is the array returned by getConnectors().
If you do not pass connectors, the SDK loads connectors through its adapter layer.


import { getConnectors } from "@dogeos/dogeos-sdk"
 
const connectors = await getConnectors()
 
const dogeConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  connectors,
}

`connect()` fails with “Provider not available for this chain type”

connect() expects a runtime wallet connector with a provider for the requested chainType.

For most apps, call openModal() instead of calling connect() directly. getConnectors() returns WalletConfig[] for configuration; those objects are not valid connect() wallet values.

”Wallet is already connected”

The SDK throws this when connect() is called for the currently connected wallet and chain type. Read isConnected before starting another connection.


const { isConnected, openModal } = useWalletConnect()
 
if (!isConnected) {
  openModal()
}

Chains

Chain switch fails

Make sure chainInfo includes the fields the wallet needs: numeric id, name, nativeCurrency, and rpcUrls.default.http.


const success = await switchChain({
  chainType: "evm",
  chainInfo: dogeOSChikyuTestnet,
})

The public type returns Promise<boolean>, but failed wallet actions may also throw. Wrap chain switching in try/catch when you need user-facing errors.

DogeOS Chikyū appears under the wrong family

DogeOS Chikyū Testnet is EVM-compatible and belongs under chains.evm.


const dogeConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  chains: {
    evm: [dogeOSChikyuTestnet],
    dogecoin: [dogecoin],
  },
}

Signing

`signMessage` is unavailable or throws “Wallet not connected”

Only call signMessage() after a wallet is connected.


const { isConnected } = useWalletConnect()
const { signMessage } = useAccount()
 
if (isConnected && signMessage) {
  await signMessage({ message: "Hello DogeOS" })
}

The SDK requires a non-empty message.

`signInWithWallet()` signs but my app is not logged in

signInWithWallet() returns a signature. Your backend still needs to verify the signature, validate the nonce, and create your app session.

Embedded Wallets

Embedded wallet stays in `initializing`

Confirm:

clientId is valid.
The current origin is registered for your integration.
Your app can load https://dogeos.embedded-wallet.tomo.inc/embed.
Your Content Security Policy allows the embedded wallet frame and relay endpoints.


<meta
  http-equiv="Content-Security-Policy"
  content="frame-src 'self' https://dogeos.embedded-wallet.tomo.inc; connect-src 'self' https://mydoge-wallet.tomo.inc https://social-relay.tomo.inc;"
/>

If you supplied custom Google or X client IDs, confirm they are registered for the origin where the app is running.


const dogeConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  login: {
    basicLogins: ["email", "externalWallets"],
    socialLogins: [
      { type: "google", clientId: "YOUR_GOOGLE_CLIENT_ID" },
      { type: "x", clientId: "YOUR_X_CLIENT_ID" },
    ],
  },
}

If you omit social clientId values, the SDK uses DogeOS defaults.

Wagmi

Wagmi hooks do not update after SDK connection

Check provider order. WalletConnectProvider must be inside WagmiProvider.


<WagmiProvider config={wagmiConfig}>
  <QueryClientProvider client={queryClient}>
    <WalletConnectProvider config={dogeConfig}>
      <App />
    </WalletConnectProvider>
  </QueryClientProvider>
</WagmiProvider>

Also confirm that the connected wallet is EVM-capable and that Wagmi has the active EVM chain configured.