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

# Troubleshooting

> Common issues and solutions when using the Embedded Wallet Kit.

## Overview

This guide provides solutions to common issues you might encounter while using `@turnkey/react-wallet-kit`. If you run into any problems, check this section first for potential fixes.

### Handling errors with `onError`

Before we begin, let's attach an `onError` callback function to the `TurnkeyProvider`. Any errors that occur during the execution of functions or initialization will be passed into this callback. This will help you debug issues more effectively.

```tsx theme={"system"}
import { TurnkeyProvider } from "@turnkey/react-wallet-kit";

function App() {
  const turnkeyConfig = {
    //... your existing configuration
  };

  return (
    <TurnkeyProvider
      config={turnkeyConfig}
      callbacks={{
        onError: (error) => {
          // You can also show a user-friendly message, toast or perform other actions here
          console.error("Error:", error);

          // Optionally, you can parse the error to get individual details
          console.error("Error details:", {
            message: error?.message,
            code: error?.code,
            cause: error?.cause,
            name: error?.name,
            stack: error?.stack,
          });
        },
      }}
    >
      {children}
    </TurnkeyProvider>
  );
}
```

## Common issues

There are a few common issues that developers or end-users may encounter when using `@turnkey/react-wallet-kit`. Here are some of them along with potential solutions:

### 1. Turnkey SDK failed to initialize

<img src="https://mintcdn.com/turnkey-0e7c1f5b/NNqJcRCxxsOsZobL/images/sdks/img/react/sdk-fail-init.png?fit=max&auto=format&n=NNqJcRCxxsOsZobL&q=85&s=bf4f31c5d324e83a67aa6e719d397888" alt="Turnkey SDK Failed to Initialize" width="455" height="460" data-path="images/sdks/img/react/sdk-fail-init.png" />

#### Problem

This error shows up when the SDK fails to initialize properly. The initialization process includes a series of network requests that must be made to Turnkey so your configuration must be correct before you launch your app.

This issue can happen for several reasons, such as:

* Missing or incorrect `authProxyConfigId` or `organizationId` in the `TurnkeyProvider` config.
* Network issues preventing the SDK from reaching Turnkey's servers.
* Incorrectly configured `apiBaseUrl` or `authProxyUrl`.
* Auth proxy not being enabled in the Turnkey Dashboard.

You can see the full error by handling it through the `onError` callback in the `TurnkeyProvider` as shown above.

#### Solution

Make sure you have the correct `authProxyConfigId` and `organizationId` in your `TurnkeyProvider` config. You can find these values in the [Turnkey Dashboard](https://app.turnkey.com).

```tsx theme={"system"}
const turnkeyConfig = {
  authProxyConfigId: process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID || "",
  organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID || "",
  // other configurations...
};
```

If you are using environment variables, ensure they are correctly set up in your `.env` file or environment configuration. You can also log these values to the console to verify they are being set correctly.

```tsx theme={"system"}
console.log(
  "Auth Proxy Config ID:",
  process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID
);
console.log("Organization ID:", process.env.NEXT_PUBLIC_ORGANIZATION_ID);
```

If you are using Turnkey's Auth Proxy, ensure it is enabled in the Turnkey Dashboard under the **Wallet Kit** section. You can also check the [Getting Started](/sdks/react/getting-started) guide for more details on setting up the Auth Poxy.

If you decide to use your own authentication setup with a backend, you can simply omit the `authProxyConfigId` from the `TurnkeyProvider` config. This will disable the Turnkey auth proxy and allow you to use your own authentication flow. Note that the **Log in or sign up** modal will not be available in this case, and you will need to implement your own authentication flow.

### 2. Proxy not enabled

<img src="https://mintcdn.com/turnkey-0e7c1f5b/NNqJcRCxxsOsZobL/images/sdks/img/react/proxy-not-enabled.png?fit=max&auto=format&n=NNqJcRCxxsOsZobL&q=85&s=ead293d5ab12ed7a647409b683faa2a6" alt="Proxy not enabled" width="455" height="460" data-path="images/sdks/img/react/proxy-not-enabled.png" />

#### Problem

This error indicates that you are trying to use the **Log in or sign up** modal without using Turnkey's auth proxy. The `authProxyConfigId` is required to use the Turnkey authentication flow.

#### Solution

To resolve this issue, you need to enable the Auth Proxy in the Turnkey Dashboard under the **Wallet Kit** section. Once enabled, you will receive an `authProxyConfigId` that you can use in your `TurnkeyProvider` config. Pass this `authProxyConfigId` to the `TurnkeyProvider` config to enable the authentication flow.

```tsx theme={"system"}
const turnkeyConfig = {
  authProxyConfigId: process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID || "",
  organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID || "",
  // other configurations...
};
```

If you prefer to use your own authentication flow, you can simply omit the `authProxyConfigId` from the `TurnkeyProvider` config. This will disable the Turnkey Auth Proxy and allow you to use your own authentication flow. Note that the **Log in or sign up** modal will not be available in this case, and you will need to implement your own authentication flow.

### 3. Turnkey styles are missing

<img src="https://mintcdn.com/turnkey-0e7c1f5b/NNqJcRCxxsOsZobL/images/sdks/img/react/styles-missing.png?fit=max&auto=format&n=NNqJcRCxxsOsZobL&q=85&s=20d7394629cfc42bf8203d86a7b7baab" alt="Turnkey styles are missing" width="525" height="359" data-path="images/sdks/img/react/styles-missing.png" />

#### Problem

This error indicates that the Turnkey styles are not being applied to the UI components. This can happen if you forget to import the styles in your main application file or if the styles are being modified by other CSS rules in your application.

#### Solution

Make sure to import the Turnkey styles in your main application file (e.g., `app/layout.tsx` in Next.js). You can do this by adding the following line at the top of your file:

```tsx theme={"system"}
import "@turnkey/react-wallet-kit/styles.css";
```

If you're using Tailwind CSS v3, please refer to the [Tailwind v3 error](#6-%40layer-utilities-is-used-but-no-matching-%40tailwind-utilities-directive-is-present-tailwind-v3-error) below for specific instructions on how to import the styles correctly.

If you are still running into the error but your styles are imported correctly, you can supress the error by adding `supressMissingStylesError: true` to the `ui` object in the `TurnkeyProvider` config. This will disable the styles check.

```tsx theme={"system"}
const turnkeyConfig = {
  //... your existing configuration
  ui: {
    suppressMissingStylesError: true, // Disable styles check. Only do this if you are sure that the styles are being applied correctly.
  },
};
```

### 4. Event handlers cannot be passed to Client Component props

<img src="https://mintcdn.com/turnkey-0e7c1f5b/NNqJcRCxxsOsZobL/images/sdks/img/react/event-handlers.png?fit=max&auto=format&n=NNqJcRCxxsOsZobL&q=85&s=de298f909272af79847cb438b6f0f8ab" alt="Event handlers cannot be passed to Client Component props" width="760" height="460" data-path="images/sdks/img/react/event-handlers.png" />

#### Problem

This error occurs when you try to pass in a callback into the `TurnkeyProvider` but you're using the `TurnkeyProvider` in a server component. In Next.js, components default to server components, which means they cannot have event handlers or state.

#### Solution

To resolve this issue, you need to ensure that the `TurnkeyProvider` is used in a client component. You can do this by adding `"use client";` at the top of your file. This will make the component a client component and allow you to pass in event handlers.

```tsx theme={"system"}
"use client";
import { TurnkeyProvider } from "@turnkey/react-wallet-kit";

function App() {
  const turnkeyConfig = {
    //... your existing configuration
  };

  return (
    <TurnkeyProvider
      config={turnkeyConfig}
      callbacks={{
        onError: (error) => console.error("Turnkey error:", error),
      }}
    >
      {children}
    </TurnkeyProvider>
  );
}
```

### 5. No active session or token available

<img src="https://mintcdn.com/turnkey-0e7c1f5b/NNqJcRCxxsOsZobL/images/sdks/img/react/no-active-session.png?fit=max&auto=format&n=NNqJcRCxxsOsZobL&q=85&s=97f506cf27f7977fd27bd48d749f61e1" alt="No active session or token available" width="736" height="102" data-path="images/sdks/img/react/no-active-session.png" />

#### Problem

This error occurs when you try to use functions that require an authenticated user, such as `handleSignMessage`, without having an active session. This can happen if the user is not logged in or if the session has expired.

#### Solution

To resolve this issue, ensure that the user is authenticated before calling functions that require an active session. You can check the `authState` variable from the `useTurnkey` hook to determine if the user is authenticated.

```tsx theme={"system"}
import { useTurnkey, AuthState } from "@turnkey/react-wallet-kit";

function AuthStatus() {
  const { authState, user, handleLogin } = useTurnkey();

  return (
    <div>
      {authState === AuthState.Unauthenticated ? (
        <p>Welcome back, {user?.userName}!</p>
      ) : (
        <button onClick={handleLogin}>Log in</button>
      )}
    </div>
  );
}
```

You can allow the session to automatically refresh by enabling the `autoRefreshSession` option in the `TurnkeyProvider` config. This will ensure that the session is refreshed before it expires, keeping the user authenticated.

```tsx theme={"system"}
const turnkeyConfig = {
  //... your existing configuration
  auth: {
    //... your existing auth configuration
    autoRefreshSession: true, // Enable automatic session refresh
  },
};
```

You can know when a session expires by using the `onSessionExpired` callback in the `TurnkeyProvider`. This will allow you to handle session expiration gracefully, such as prompting the user to log in again.

```tsx theme={"system"}
<TurnkeyProvider
  config={turnkeyConfig}
  callbacks={{
    onSessionExpired: () => {
      console.log("Session expired. Please log in again.");
      // Optionally, you can redirect the user to the login page or show a modal
    },
  }}
>
  {children}
</TurnkeyProvider>
```

### 6. `@layer utilities` is used but no matching `@tailwind utilities` directive is present (Tailwind V3 error)

<img src="https://mintcdn.com/turnkey-0e7c1f5b/NNqJcRCxxsOsZobL/images/sdks/img/react/tw3-error.png?fit=max&auto=format&n=NNqJcRCxxsOsZobL&q=85&s=73fcfb3e15633d859af106787b303851" alt="Tailwind utilities error" width="992" height="843" data-path="images/sdks/img/react/tw3-error.png" />

#### Problem

This error occurs after importing the Turnkey styles in a Tailwind CSS project using Tailwind CSS v3. `@turnkey/react-wallet-kit` is built with Tailwind CSS v4 under the hood, and exports the styles into a regular CSS file for importing into any project. However, if you are using Tailwind CSS v3, you may encounter this error because Tailwind CSS v3 uses different syntax for CSS directives. Note that this error does not occur in Tailwind CSS v4 projects or when Tailwind CSS is not installed at all.

#### Solution

We recommend upgrading to Tailwind CSS v4 since this is currently the latest version. You can use the official [Tailwind CSS upgrade guide](https://tailwindcss.com/docs/upgrade-guide) to help you with the upgrade process.

If you cannot upgrade to Tailwind CSS v4, you can follow these steps to resolve the issue:

<Steps>
  <Step title="Install postcss-import">
    Install `postcss-import` if you haven't already:

    ```bash theme={"system"}
    npm install -D postcss-import
    ```
  </Step>

  <Step title="Add postcss-import to your PostCSS config">
    Add postcss-import to your `postcss.config.mjs` (or equivalent) file:

    ```js theme={"system"}
    /** @type {import('postcss-load-config').Config} */
    const config = {
      plugins: {
        tailwindcss: {},
        "postcss-import": {}, // Add postcss-import here
      },
    };

    export default config;
    ```
  </Step>

  <Step title="Import Turnkey styles in your main CSS file">
    Import the Turnkey styles in your main CSS file (e.g., `styles/globals.css`):

    We usually recommend importing the styles in your main application file (e.g., `app/layout.tsx` in Next.js) however, if you're using Tailwind CSS v3, you can't do this. Please remove the import if you already have it in your main application file.

    For Tailwind CSS v3, you need to import the Turnkey styles in your main CSS file (e.g., `styles/globals.css`) by pointing the import to `@turnkey/react-wallet-kit/dist/styles.css` file:

    ```css theme={"system"}
    @import "@turnkey/react-wallet-kit/dist/styles.css";

    @tailwind base;
    @tailwind components;
    @tailwind utilities;
    ```

    The Turnkey styles must be imported before the Tailwind directives to ensure that the styles are applied correctly. You also must point to the `dist` directory to properly retrieve the styles (`@turnkey/react-wallet-kit/dist/styles.css` instead of `@turnkey/react-wallet-kit/styles.css`).
  </Step>
</Steps>

### 7. Radix UI overlapping portals

<img src="https://mintcdn.com/turnkey-0e7c1f5b/NNqJcRCxxsOsZobL/images/sdks/img/react/radix-bug.gif?s=24753124620dfe0169d5f153c1b7a57d" alt="Radix UI overlapping portals" width="540" height="540" data-path="images/sdks/img/react/radix-bug.gif" />

#### Problem

This issue occurs when using certain Radix UI components (e.g., Dialog, DropdownMenu, etc.) in the same application as `@turnkey/react-wallet-kit`. Radix UI uses portals to render components outside of the main DOM hierarchy, which can cause conflicts when trying to open a Turnkey modal while a Radix UI component is also open. You may notice that the Turnkey modal becomes unresponsive or that the Radix UI component remains open and blocks interaction with the Turnkey modal.

#### Solution

We recommend avoiding using portal-based components from Radix UI (or similar libraries that use portals) while Turnkey's modals are open. You can also try switching to [`headless-ui`](https://headlessui.com/) components since Turnkey's modals are built with [`headless-ui`](https://headlessui.com/) under the hood.

If you cannot avoid using Radix UI components, you can try the following workaround:

<Steps>
  <Step title="Update your global CSS file">
    Add the following CSS to your global CSS file (e.g., `styles/globals.css`):

    ```css theme={"system"}
    #headlessui-portal-root {
      pointer-events: auto;
    }
    ```

    This will apply `pointer-events: auto;` to the Turnkey modal portal, allowing it to receive pointer events even when other portals are open.
  </Step>

  <Step title="Modify your Radix UI components">
    You need to prevent outside click events from closing the Radix UI components when the Turnkey modal is open.

    You can do this by adding the following `onPointerDownOutside` handler to your Radix UI components:

    ```tsx theme={"system"}
    import { useModal } from "@turnkey/react-wallet-kit";
    import * as Dialog from "@radix-ui/react-dialog";

    const { modalStack } = useModal();  // Get the modal stack from Turnkey's modal system
    return (
      {/* Your dialog root, trigger, overlay, etc. */}
      <Dialog.Content
        onPointerDownOutside={(e) => {
          if (modalStack.length > 0) {
            e.preventDefault();
          }
        }}
      >
        {/* Your dialog content */}
      </Dialog.Content>
    )
    ```

    Overall, your Radix UI dialog component (or similar) should look something like this:

    ```tsx theme={"system"}
    import { useModal } from "@turnkey/react-wallet-kit";
    import * as Dialog from "@radix-ui/react-dialog";

    function RadixDialog() {
      const { modalStack } = useModal(); // Get the modal stack from Turnkey's modal system

      return (
        <Dialog.Root>
          <Dialog.Trigger>Open Dialog</Dialog.Trigger>
          <Dialog.Portal>
            <Dialog.Overlay />
            <Dialog.Content
              onPointerDownOutside={(e) => {
                if (modalStack.length > 0) {
                  e.preventDefault();
                }
              }}
            >
              {/* Your dialog content */}
            </Dialog.Content>
          </Dialog.Portal>
        </Dialog.Root>
      );
    }
    ```
  </Step>
</Steps>

### 8. Module not found. The extension in the request is mandatory for it to be fully specified (Create React App)

<img src="https://mintcdn.com/turnkey-0e7c1f5b/jAj4o4kZDAeCCL_e/images/sdks/img/react/fully-specified.png?fit=max&auto=format&n=jAj4o4kZDAeCCL_e&q=85&s=a046504403878c2c62ee7c047e003f86" alt="Create React App error" width="1877" height="353" data-path="images/sdks/img/react/fully-specified.png" />

#### Problem

This error occurs when using Create React App (CRA) and trying to import `@turnkey/react-wallet-kit`. CRA requires that all imports include the file extension to be fully specified. Note that this can also occur in strict ESM build environments (e.g., Next.js builds in CI) where fully specified imports are required. In those cases you may see errors like: `Cannot find module '@turnkey/core/dist/__types__/enums'` and a suggestion to import `@turnkey/core/dist/__types__/enums.js`. The fix is to ensure the import is resolved with the `.js` extension (e.g., `@turnkey/core/dist/__types__/enums.js`). If you can't edit the package source directly, apply a small build-time patch that rewrites the import.

#### Solution

Follow these steps to resolve the issue:

<Steps>
  <Step title="Eject from Create React App (CRA)">
    Ejecting from CRA will give you full control over the Webpack configuration, allowing you to modify it to remove the need for fully specified imports.

    ```bash theme={"system"}
    npm run eject
    ```

    Note that this action is irreversible, so make sure to commit your changes before ejecting.
  </Step>

  <Step title="Modify the Webpack configuration">
    After ejecting, open the `config/webpack.config.js` file and locate the `resolve` section. Add the following line to the `resolve` object under the rules for `/\.(js|mjs)$/` files:

    ```js theme={"system"}
    // config/webpack.config.js

    // ... other configurations
    {
      test: /\.(js|mjs)$/,  // Search for this line
      exclude: /@babel(?:\/|\\{1,2})runtime/,
      loader: require.resolve('babel-loader'),

      resolve: {
        fullySpecified: false,  // Add this line
      },



    // ... other configurations
    }
    ```

    This will disable the requirement for fully specified imports in your project.
  </Step>
</Steps>

Read more about fully specified imports in the [Webpack documentation](https://webpack.js.org/configuration/module/#resolvefullyspecified).

### 9. Client is not initialized error when using Turnkey functions

<img src="https://mintcdn.com/turnkey-0e7c1f5b/UH0IpQZKxOCWYLv7/images/sdks/img/react/client-not-initialized.png?fit=max&auto=format&n=UH0IpQZKxOCWYLv7&q=85&s=c3b54bd6dc9748db165692e637890ac3" alt="Client is not initialized error" width="514" height="167" data-path="images/sdks/img/react/client-not-initialized.png" />

#### Problem

This error occurs when you try to use Turnkey client functions before the SDK has finished initializing said client. The Turnkey SDK performs several asynchronous operations during initialization, and if you attempt to call client functions before this process is complete, you'll encounter this error.

#### Solution

To resolve this issue, ensure that you only call Turnkey client functions after the SDK has fully initialized. You can do this by checking the `clientState` state variable from the `useTurnkey` hook. The `clientState` variable indicates the current state of the Turnkey client. You can read up more about how to use the `clientState` variable and why its important in the [Getting Started](/sdks/react/getting-started#client-readiness) guide.

Example solutions to potential issues:

**Calling client functions in `useEffects` or event handlers without checking client readiness:**

```tsx theme={"system"}
import { useTurnkey } from "@turnkey/react-wallet-kit";

const { handleSignMessage } = useTurnkey();

useEffect(() => {
  handleSignMessage({
    message: "Hello, Turnkey!",
    walletAccount: activeWalletAccount,
  });
}, []);
```

**Fix: Check `clientState` before calling client functions:**

```tsx theme={"system"}
import { ClientState, useTurnkey } from "@turnkey/react-wallet-kit";

const { clientState, handleSignMessage } = useTurnkey();

useEffect(() => {
  if (clientState === ClientState.Ready) {
    handleSignMessage({
      message: "Hello, Turnkey!",
      walletAccount: activeWalletAccount,
    });
  }
}, [clientState]);
```