Troubleshooting

This guide covers common issues you may encounter while using OnchainKit. If you don't find your issue here, try searching our GitHub Issues or joining our Discord Community.

Common Issues

Environment Setup

Missing API Key
- Error: "Project ID is required for this component"
- Solution: Add your Client API Key to .env:
```
NEXT_PUBLIC_CDP_API_KEY=YOUR_PUBLIC_API_KEY
```
Invalid Environment Variables
- Error: "Cannot find environment variable"
- Solution: Use the correct variable name for your framework:
  - Next.js: NEXT_PUBLIC_CDP_API_KEY
  - Vite: VITE_PUBLIC_ONCHAINKIT_API_KEY
  - Astro: PUBLIC_ONCHAINKIT_API_KEY
Contracts Not Available
- Error: "Contracts are not available" or "Contracts not available for LifecycleStatus"
- Solutions:
  - Verify NEXT_PUBLIC_ONCHAINKIT_API_KEY is set correctly
  - For Checkout component with chargeHandler, also set:
    NEXT_PUBLIC_COINBASE_COMMERCE_API_KEY=YOUR_COMMERCE_API_KEY
  - Ensure API keys are properly exposed in your environment

Dependencies

Version Compatibility

Issue: Unexpected behavior or type errors

Solution: Ensure compatible versions:

{
  "dependencies": {
    "@coinbase/onchainkit": "latest",
    "viem": "^2.0.0",
    "@wagmi/core": "^2.0.0"
  }
}

Provider Configuration

Missing OnchainKitProvider

Error: "OnchainKit context not found"
Solution: Wrap your app with OnchainKitProvider and configure properly:

import { OnchainKitProvider } from '@coinbase/onchainkit';
import { base } from 'viem/chains';
 
export default function App({ children }) {
  return (
    <OnchainKitProvider
      apiKey={process.env.NEXT_PUBLIC_CDP_API_KEY}
      chain={base}
    >
      {children}
    </OnchainKitProvider>
  );
}

Wallet Connection

Connection Failed
- Error: "Unable to connect wallet"
- Solutions:
  - Verify wallet extension is installed and unlocked
  - Check supported chains configuration
  - Ensure proper network selection in wallet
  - Verify RPC endpoints are accessible
Chain Switching Issues
- Error: "Failed to switch chain"
- Solutions:
  - Verify chain ID is supported by OnchainKit
  - Check wallet has required permissions
  - Ensure RPC endpoints are configured correctly
  - Add chain to wallet if not already added

Transaction Issues

Gas Estimation Failed
- Error: "Gas estimation failed"
- Solutions:
  - Verify sufficient balance for gas
  - Check transaction parameters are valid
  - Ensure proper network configuration

Identity Components

Theme Issues

Dark Mode Not Working

Error: "Dark mode styles not applying"
Solution: Configure Tailwind and OnchainKit properly:

// tailwind.config.js
module.exports = {
  darkMode: ['class'],
  safelist: ['dark'],
  // ... rest of config
}

React Native

** React Native Support **
- OnchainKit's components are not supported for use in React Native, however, you can use utility functions, like getName, as well as some hooks in your React Native app. When using these utility functions, you may need to import them directly rather than through the export file.
- Example: import { getName } from '@coinbase/onchainkit/esm/identity/utils/getName.js'; rather than import { getName } from '@coinbase/onchainkit/identity;

Module Resolution

Module Resolution Errors
- Error: "Cannot find module ... or its corresponding type declarations. Consider updating to 'node16', 'nodenext', or 'bundler'"
- Solution: Update your Node.js version or use a compatible bundler. We recommend using Node 18+ and "moduleResolution": "NodeNext" for the best developer experience. OnchainKit supports only ES Modules and does not support CommonJS modules.

Getting Help

Need more help?