Skip to Content
On this page

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>
  )
}

The modal opens but looks unstyled#

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 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. Check whether app styles are clipping or covering the modal.

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. Create a project in the developer console  and copy the Sandbox or Live client ID for the environment your app uses. Check that environment’s origin settings; see Get a Client ID.

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#

An embedded login popup appears inside MyDoge#

Upgrade the deployed SDK and lockfile to 4.0.4 or later v4, then use the normal WalletConnectProvider and openModal() flow. The SDK chooses the injected native wallet before embedded initialization. Remove custom code that independently starts an embedded wallet inside MyDoge; keep ordinary-browser social login enabled. See Native-First Connection.

MyDoge reports “MyDoge is not ready to connect”#

SDK 4.0.4 continues checking for native readiness after the initial startup timeout and resumes when a valid MyDoge provider becomes ready. You can also use the displayed Retry action. If the message remains, confirm that you are on the approved top-level dApp page in MyDoge and that the deployed bundle and lockfile resolve to 4.0.4. Do not add an embedded-login fallback to bypass native startup.

Native approval is followed by 4001 or an unchanged Connect button#

4001 alone does not establish which request failed or why. Expose the connection error and offer an explicit retry. Disable duplicate attempts while a request is pending. With a custom provider integration, await connection before account/chain reads and avoid overlapping native requests. Native wallet requests must come from the approved top-level page; ordinary chart/content frames can remain.

If the failure persists, record Android/iOS, MyDoge build, SDK version, page URL, failing method, numeric error code and request order. Do not include authentication tokens, signatures or private wallet data.

The account is stale or MyDoge disappears after disconnect#

Use the current SDK account, provider and chain after restoration; do not mark a cached address connected before validation. After explicit disconnect, wait for a manual reconnect rather than immediately reconnecting from an effect. If you use a custom Wagmi or RainbowKit picker, keep the discovered MyDoge provider available on mobile instead of filtering it out solely because optional display metadata is missing. Replacing a working custom connector is not required.

WalletConnect is missing from the wallet list#

In SDK 4.0.4, you must supply your own walletConnectProjectId; the SDK has no fallback project. An omitted or blank value disables WalletConnect without disabling email, social login, or injected wallets. Create a project in the Reown dashboard  and follow WalletConnect configuration.

If you supplied a project ID but connection fails, check the ID and any Reown origin allowlist. Your DogeOS client ID cannot be used as a WalletConnect project ID.

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.

import { ChainTypeEnum } from "@dogeos/dogeos-sdk"
 
const success = await switchChain({
  chainType: ChainTypeEnum.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],
  },
}

Solana WalletConnect sessions do not match#

Use the Solana entries from getChains() as shown in Dynamic Chains. They carry the canonical identifiers needed for WalletConnect matching. Do not replace the mainnet identifier with solana:mainnet-beta.

Signing#

Does signing require Ethereum mainnet?#

No. MyDoge supports message signing on DogeOS Testnet and other supported EVM networks. Authenticate on the intended chain with a matching server challenge. SIWE is a message format, not a requirement to switch to Ethereum mainnet.

Keep contract requests, permits and EIP-712 domains bound to their actual chain. Do not change them to chain 1 to sign in.

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.

If the backend provided a complete challenge message, preserve it with signMessage({ message }). Follow the exact-message authentication workflow and discard the challenge if the wallet account or chain changes.

Embedded wallet typed-data signing reports a chain mismatch#

For EVM typed-data signing, make sure domain.chainId matches the active EVM chain. DogeOS Chikyū Testnet should use decimal 6281971 or hex 0x5fdaf3. Switch to the intended chain before requesting the signature.

Embedded Wallets#

Embedded wallet stays in initializing#

Confirm:

  • You are using your registered DogeOS client ID.
  • Your exact app origin is registered, including the port for local development.
  • Your browser can load https://embedded-wallet.mydoge.com/embed.
  • Your Content Security Policy allows the production SDK origins.

Use http://localhost:5173 if that is the origin registered for local testing. Changing the hostname or port requires that origin to be registered too.

In ordinary browsers, external wallet connection remains available while the embedded wallet initializes. Social-login buttons may be disabled until walletStatus becomes "ready". In MyDoge’s native-first flow, walletStatus: "disabled" is expected; use isConnected and the current provider rather than waiting for embedded readiness.

Social login fails#

Allow the login popup and check that the current app origin is registered for your DogeOS client ID. DogeOS manages Google and X authentication; the login option only controls which methods appear.

If login succeeds but the wallet keeps loading, capture the browser error and the failing request’s status. Share those details with DogeOS support along with your client ID and app origin. Do not include session tokens or login codes.

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.

Integration Acceptance Checks#

Use the SDK demo repository  as the reference and test your actual deployed app:

  • Connect inside MyDoge with your normal charts/frames present and no competing embedded-wallet login.
  • Verify current account and chain after a cold load and reload.
  • Cancel a request, retry, then disconnect and manually reconnect without duplicate requests.
  • Change account or network during sign-in; discard stale work and show the actual wallet state.
  • Verify DogeOS authentication through your server, separately from a connection or demonstration signature.
  • Check ordinary-browser social login separately and confirm your intended flow on Android and iOS.

Reference#