> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for the most common issues when integrating Helius embedded wallets — styling, sign-in, signing, sending, and API-key access.

Common issues when integrating the [`helius-wallet-kit`](https://www.npmjs.com/package/helius-wallet-kit) SDK, and how to fix them.

## Setup

### The wallet modal is unstyled or looks broken

The SDK's stylesheet isn't loaded. Import it once in your root layout:

```tsx app/layout.tsx theme={"system"}
import "helius-wallet-kit/ui/styles.css";
```

### The hook values never change (stuck on `loading`)

`useHeliusWallet()` only works inside `HeliusWalletProvider`, and the provider must be a **client** component. Make sure the provider wraps your component tree from a file with `"use client"` at the top — see [Setup](/docs/waas/quickstart#setup).

### `[HeliusWalletKit] WaaS bootstrap failed (…)` in the console

The provider couldn't resolve your project from the API key. Check that:

* `NEXT_PUBLIC_HELIUS_API_KEY` is set and valid.
* The project is on a **paid plan** with embedded wallets enabled.
* If you domain-restricted the key, your current origin is in the allowed list — see [Securing your key](/docs/waas/securing-your-key).

## Sign-in

### Users land on an "upgrade" screen instead of the wallet

Embedded wallets require a **paid** Helius plan. When the resolved plan is free, the provider renders an upgrade prompt (and the backend rejects the request server-side too). Upgrade the project in the [dashboard](https://dashboard.helius.dev).

### The wrong sign-in methods appear (e.g. Google shows, external wallet is missing)

Sign-in methods come from your project config in the [dashboard](https://dashboard.helius.dev) under **WaaS → Configuration**. If a project has none configured, the modal falls back to an org-wide default. Set the methods you want in the dashboard, or pass `authMethods` to the provider `config` to override per environment — see [Configure sign-in methods](/docs/waas/configuration#configure-sign-in-methods).

### Passkey sign-in fails or says the passkey isn't registered

Passkeys are bound to the **domain and authenticator** they were created on (a WebAuthn constraint, not a Helius one). A passkey or security key registered on another site or device won't authenticate your app. Create the passkey on the domain you're testing — note that a passkey made on `localhost` is bound to `localhost` and won't carry over to your deployed domain.

## Signing and sending

### `No wallet available` when signing

You called a signing method before the embedded wallet finished provisioning. Gate signing on both `status === "authenticated"` **and** a non-null `address`:

```tsx theme={"system"}
const { status, address, signMessage } = useHeliusWallet();
const ready = status === "authenticated" && address;
```

### `… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler`

You're running in direct (Secure RPC) mode, and this call — a **send** or **priority-fee** request — needs the server route handler. Mount it at `/api/helius/[...path]` and set `HELIUS_API_KEY`:

```ts app/api/helius/[...path]/route.ts theme={"system"}
import { createHeliusRouteHandler } from "helius-wallet-kit/next";

export const { GET, POST } = createHeliusRouteHandler();
```

See [the server route handler](/docs/waas/quickstart#setup).

### `getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode`

Transaction history is only available through the route handler. Add it as shown above.

### `getPriorityFeeEstimate is not available`

Devnet doesn't support priority-fee estimates — it's a mainnet feature. Skip the lookup on devnet; sends still work without a priority fee.

```tsx theme={"system"}
if (cluster === "mainnet-beta") {
  const fees = await getPriorityFeeLevels([address]);
}
```

### A transaction doesn't land on mainnet

Without the route handler, sends use standard RPC rather than [Helius Sender](/docs/sending-transactions/sender), so they forgo Sender's optimized landing. Mount the route handler for best mainnet landing. If a send fails outright, refresh the blockhash — a stale `recentBlockhash` expires quickly.

## Keys and access

### RPC or API calls are rejected (401 / 403) after locking your key

Your domain-restricted key doesn't include the origin you're calling from. Add every origin you use — production, staging, preview deploys, and `localhost` for development — under **RPC Access Control**. See [Securing your key](/docs/waas/securing-your-key).

## Still stuck?

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.com/invite/6GXdee3gBj">
    Ask the community and the Helius team.
  </Card>

  <Card title="Support" icon="headset" href="/docs/support">
    Contact Helius support.
  </Card>
</CardGroup>