Vue Solana Logo

Troubleshooting

Common setup, TypeScript, wallet, RPC, and Nuxt issues.

Use this guide to diagnose the most common Vue Solana setup issues across Vue, Nuxt, TypeScript, wallet discovery, RPC calls, and transactions. Start with the error message or behavior that matches your app, then follow the checks in order before opening an issue.

TypeScript Cannot Resolve @solana/web3-compat

@solana/web3-compat@0.0.21 currently has broken TypeScript metadata. Runtime imports still use the real package. Current Vue Solana packages publish temporary package-owned declaration shims, so the documented imports from @vue-solana/core, @vue-solana/vue, and @vue-solana/nuxt should typecheck without a consumer-local shim.

If TypeScript still reports missing declarations, first confirm that you are using a current Vue Solana package version and are not importing @solana/web3-compat directly from app code. For older Vue Solana versions or direct @solana/web3-compat imports, add types/web3-compat.d.ts to your app:

declare module "@solana/web3-compat" {
  export type {
    Commitment,
    RpcResponseAndContext,
    SendOptions,
    SignatureResult,
    TransactionSignature,
  } from "@solana/web3.js";
  export {
    Connection,
    Keypair,
    PublicKey,
    SystemProgram,
    Transaction,
    TransactionInstruction,
    VersionedTransaction,
  } from "@solana/web3.js";
}

Make sure your tsconfig.json includes the file:

{
  "include": ["src/**/*.ts", "src/**/*.vue", "types/**/*.d.ts"]
}

Re-check new @solana/web3-compat versions before keeping this workaround. The package-owned shim should be removed once upstream ships valid root declarations.

Vue Solana plugin is not installed

This means client-side code tried to use the Solana connection or wallet actions without installing the plugin. Current composables return inert SSR-safe state when Nuxt renders on the server, but real RPC and wallet operations still require the client plugin context.

For Vue:

createApp(App).use(
  createSolanaPlugin({
    cluster: "devnet",
  }),
);

For Nuxt, register the module:

export default defineNuxtConfig({
  modules: ["@vue-solana/nuxt"],
});

The Nuxt module keeps the Vue Solana plugin client-only. Auto-imported composables can be called during SSR, but avoid doing direct RPC or wallet work on the server. Trigger RPC reads from client lifecycle hooks or user actions when you need the real Solana connection.

No Solana wallet is configured

No wallet has been selected or manually configured. Use useWallets() or useSolanaWallets() to select a discovered wallet before calling connect() or sending a transaction.

const { wallets, selectWallet } = useSolanaWallets();

selectWallet(wallets.value[0]);

RPC reads and balance reads work without a wallet.

No Browser Wallets Are Detected

Common causes:

  • No Solana wallet extension is installed.
  • The wallet extension is disabled for the current browser profile.
  • The app is running in SSR or a non-browser environment.
  • The wallet does not implement the Wallet Standard.

Install a wallet such as Phantom, Solflare, or Backpack, then call refreshWallets() after the page loads.

Mobile Wallet Adapter Is Not Detected

Android Mobile Wallet Adapter web registration works only on supported Android Chrome mobile web and Chrome PWA runtimes.

Common causes:

  • The app is running on desktop, iOS, Firefox Android, Brave Android, Opera Android, or another unsupported browser.
  • No compatible Solana mobile wallet is installed.
  • mobileWallet: false was passed to the Vue plugin or Nuxt module.
  • Wallet discovery ran before hydration or before the page could access window.

Open the app in Android Chrome, install a compatible wallet, then call refreshWallets() after the page loads.

iOS Wallet Link Does Not Complete

iOS wallet support uses Phantom, Solflare, and Backpack universal links. The wallet app redirects back to your app URL after approval.

Common causes:

  • The app is not running in an iOS browser.
  • Phantom, Solflare, or Backpack is not installed on the device.
  • iosWallet: false was passed to the Vue plugin or Nuxt module.
  • The configured redirectUrl does not return to the same app page that refreshes wallet state.
  • Wallet refresh or callback handling is only running during SSR instead of on the client.

Keep iOS wallet work client-side, make sure the redirect URL loads the app again, and call refreshWallets() after the redirected page loads. The Vue plugin handles iOS callbacks during wallet refresh; apps using core helpers directly should call handleSolanaIosWalletCallback() before relying on the returned connection.

Solana wallet is not connected

The transaction helper was called before the wallet reported connected: true and a non-null publicKey.

Call connect() first, or check connected.value before sending.

Wallet Appears Connected After Refresh During Local Development

Selecting a discovered wallet should not mark it connected. connected should become true only after connect() succeeds, even if the browser extension exposes previously authorized accounts.

If local Vue or Nuxt examples still appear connected immediately after refresh, rebuild the workspace packages and fully restart the dev server so Vite/Nuxt drop stale package output:

pnpm build:packages
pnpm dev:vue

For Nuxt, use pnpm dev:nuxt after rebuilding packages.

Solana wallet does not support signTransaction

The configured wallet does not expose either signAndSendTransaction or signTransaction. Use a wallet that supports transaction signing for the selected Solana chain.

Wallet Transaction Did Not Return A Result

This can happen when a wallet adapter starts a mobile handoff but never settles its browser promise. Vue Solana clears loading and sets error instead of leaving the app stuck in a sending state. The transaction may still have succeeded if the wallet submitted it before the response was lost, so check the wallet activity or a Solana explorer before retrying.

Android Mobile Wallet Adapter wallets prefer wallet signing plus app-side RPC submission when signTransaction is available. That path avoids the common case where the wallet sends successfully but the browser page never receives the adapter's returned signature.

Buffer is not defined

Some @solana/web3-compat transaction paths still expect a Node-compatible Buffer global. In browser Vue apps, initialize the Vue package Buffer polyfill before creating or serializing transactions. Use @vue-solana/nuxt/buffer-polyfill in Nuxt apps.

import { installSolanaBufferPolyfill } from "@vue-solana/vue/buffer-polyfill";

installSolanaBufferPolyfill();

The helper is provided by the framework packages, so apps do not need to install or import buffer directly for Vue Solana transaction examples.

Module buffer Has Been Externalized

If the console says Module "buffer" has been externalized for browser compatibility, replace direct app imports from buffer with installSolanaBufferPolyfill() from @vue-solana/vue/buffer-polyfill or @vue-solana/nuxt/buffer-polyfill, then restart the dev server. Vite may cache the previously optimized dependency.

Balance Reads Fail

Common causes:

  • The address string is not a valid Solana public key.
  • The RPC endpoint is unavailable or rate-limited.
  • The wallet address is on a different cluster than the configured RPC endpoint.

Check the configured cluster and endpoint with useRpc() or useSolanaRpc().

Nuxt Auto-Imports Are Missing

Make sure @vue-solana/nuxt is listed in modules and restart the Nuxt dev server after installing the package.

If TypeScript still does not recognize auto-imports, regenerate Nuxt types:

npx nuxi prepare

Agent Skill

Solana For Vue Developers