Skip to main content

Troubleshooting

Common issues and solutions when using react-native-rgb.

iOS Issues​

Framework Download Fails​

If the postinstall script fails to download the rgb_libFFI.xcframework, manually download it:

node scripts/download-rgb-lib-ios.js

Or from the project root:

cd /path/to/react-native-rgb
node scripts/download-rgb-lib-ios.js

Linker Errors​

Problem: Build errors related to missing symbols or framework linking.

Solution:

  • Always use the .xcworkspace file, not the .xcodeproj file
  • Clean build folder: Product > Clean Build Folder (Cmd+Shift+K)
  • Delete derived data and rebuild
  • Ensure CocoaPods are up to date: pod repo update

Framework Not Found​

Problem: rgb_libFFI.xcframework not found during build.

Solution:

  1. Verify the framework exists in ios/rgb_libFFI.xcframework
  2. Check that the framework is included in your Xcode project
  3. Ensure the framework path is correct in Podfile or project settings
  4. Run pod install again

Android Issues​

minSdkVersion Error​

Problem: Build fails with "minSdkVersion" error.

Solution: Ensure your android/build.gradle has:

android {
    defaultConfig {
        minSdkVersion 24  // Must be at least 24
    }
}

JitPack Repository Missing​

Problem: Dependency resolution fails.

Solution: Add JitPack to your android/build.gradle:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
        // ... other repositories
    }
}

Gradle Sync Issues​

Problem: Gradle sync fails or dependencies are not resolved.

Solution:

  1. Clean the project: cd android && ./gradlew clean
  2. Invalidate caches in Android Studio: File > Invalidate Caches / Restart
  3. Delete .gradle folder in the android directory
  4. Re-sync Gradle

Runtime Issues​

Wallet Not Initialized​

Problem: Error when calling wallet methods: "Wallet is not initialized"

Solution:

  • The wallet initializes automatically on first use
  • Ensure you've created a Wallet instance with valid keys
  • Check that keys were generated/restored successfully

goOnline Fails​

Problem: goOnline() throws an error or times out.

Solution:

  • Verify the indexer URL is correct and accessible
  • Check network connectivity
  • Try a different indexer URL
  • Ensure the wallet instance is valid
  • Check if the indexer requires authentication

Insufficient UTXOs​

Problem: Error when issuing assets or creating transfers: "Insufficient UTXOs"

Solution:

  • Create more UTXOs using createUtxos()
  • Ensure you have sufficient Bitcoin balance for UTXO creation
  • Check that UTXOs are settled (not pending)

Asset Not Found​

Problem: getAssetBalance() or getAssetMetadata() throws "Asset not found"

Solution:

  • Verify the asset ID is correct
  • Ensure the asset exists in your wallet (check with listAssets())
  • The asset may need to be received first via blindReceive() or witnessReceive()

Transaction Broadcast Fails​

Problem: Transaction created but broadcast fails.

Solution:

  • Check network connectivity
  • Verify the wallet is online (goOnline() was called)
  • Ensure sufficient fee rate
  • Check if the transaction is valid (not double-spending)

Error Handling​

All methods throw RgbError with specific error codes. Handle errors properly:

import { RgbError, RgbErrorCode } from 'react-native-rgb';

try {
  await wallet.goOnline('ssl://indexer.example.com:50053');
} catch (error) {
  const rgbError = RgbError.fromReactNativeError(error);
  
  if (rgbError instanceof RgbError) {
    switch (rgbError.code) {
      case RgbErrorCode.GO_ONLINE_ERROR:
        console.error('Failed to connect:', rgbError.message);
        break;
      case RgbErrorCode.INSUFFICIENT_BITCOINS:
        console.error('Insufficient funds:', rgbError.message);
        break;
      default:
        console.error(`Error [${rgbError.code}]:`, rgbError.message);
    }
  }
}

Common Error Codes​

  • GO_ONLINE_ERROR: Failed to connect to indexer
  • INSUFFICIENT_BITCOINS: Not enough Bitcoin for the operation
  • INSUFFICIENT_ASSIGNMENTS: Not enough asset balance
  • INVALID_ASSET_ID: The provided asset ID is invalid
  • OFFLINE: Wallet is not online (call goOnline() first)
  • INVALID_INVOICE: Invoice string is malformed
  • INVALID_ADDRESS: Bitcoin address is invalid

Performance Tips​

  1. Batch Operations: When possible, batch multiple operations
  2. Skip Sync: Use skipSync: true when you don't need the latest state
  3. Close Wallet: Always call wallet.close() when done to free resources
  4. UTXO Management: Create UTXOs in advance rather than on-demand

Getting Help​

If you're still experiencing issues:

  1. Check the GitHub Issues
  2. Review the Usage documentation for method details
  3. Ensure you're using the latest version of the library
  4. Check that your React Native version is compatible (0.70+)

Debugging​

Enable verbose logging in development:

// Check wallet state
const walletData = await wallet.getWalletData();
console.log('Wallet data:', walletData);

// List all assets
const assets = await wallet.listAssets([]);
console.log('Assets:', assets);

// List all transfers
const transfers = await wallet.listTransfers(null);
console.log('Transfers:', transfers);