Troubleshooting

​

Common Issues

​

”No staking contract configured for chain …”

import { StarkZap } from "starkzap";

// Recommended: use built-in chain-aware staking preset
const sdk = new StarkZap({ network: "mainnet" });

​

Transaction Submits but Explorer URL Points to Wrong Explorer

const sdk = new StarkZap({
  network: "mainnet",
  explorer: { provider: "starkscan" }, // or "voyager" (default)
});

​

React Native Random Values/Text Encoding Issues

1. Follow React Native Integration
2. Ensure your metro.config.js is wrapped with withStarkzap(...)
3. Clear Metro cache after dependency changes (npx expo start -c)

npm install react-native-get-random-values fast-text-encoding buffer @ethersproject/shims

import "react-native-get-random-values";
import "fast-text-encoding";
import "@ethersproject/shims";

​

Account Not Deployed Error

// Option 1: Use ensureReady
await wallet.ensureReady({ deploy: "if_needed" });

// Option 2: Deploy explicitly
if (!(await wallet.isDeployed())) {
  await wallet.deploy();
}

// Option 3: Use onboard API which handles this automatically
const onboard = await sdk.onboard({
  strategy: OnboardStrategy.Signer,
  account: { signer },
  deploy: "if_needed",
});

​

Privy Signer Backend Not Responding

1. Verify your backend endpoint is accessible
2. Ensure the endpoint accepts POST requests with { walletId, hash }
3. Check that the endpoint returns { signature } in the correct format
4. Verify CORS settings if calling from a browser

// Express.js example
app.post("/api/wallet/sign", async (req, res) => {
  const { walletId, hash } = req.body;
  const signature = await privyClient.wallets().rawSign(walletId, {
    params: { hash },
  });
  res.json({ signature });
});

​

Cartridge Connection Fails

1. Ensure @cartridge/controller is installed
2. Check that you’re calling connectCartridge in a browser environment
3. Verify network configuration matches Cartridge’s supported networks
4. Check browser console for Cartridge-specific errors

​

Bridge Token Loading Fails

1. Verify the SDK chain config is correct (SN_MAIN vs SN_SEPOLIA) and matches your intended environment
2. Confirm network access to the token API endpoint used by the SDK
3. Install required optional deps for the chains you use:
   • Ethereum routes: ethers
   • Solana routes: @solana/web3.js (and Hyperlane packages for Solana bridge operations)

npm install ethers @solana/web3.js @hyperlane-xyz/sdk @hyperlane-xyz/registry @hyperlane-xyz/utils

​

OFT Bridge Fails with LayerZero API Key Error

1. Set bridging.layerZeroApiKey in new StarkZap({ ... })
2. Use a mainnet route for OFT/OFT-migrated bridge flows

const sdk = new StarkZap({
  network: "mainnet",
  bridging: {
    layerZeroApiKey: "YOUR_LAYERZERO_API_KEY",
  },
});

​

Bridge Deposit Fails with Chain Mismatch

1. Ensure the selected BridgeToken.chain matches the connected external wallet type
2. Ensure external wallet network and Starknet network pairing is valid (mainnet with mainnet, testnet with testnet)
3. Recreate connected external wallets with ConnectedEthereumWallet.from(...) / ConnectedSolanaWallet.from(...) after network switch

​

Amount Arithmetic Errors

// ❌ This will throw
const a = Amount.parse("10", STRK); // 18 decimals
const b = Amount.parse("5", USDC); // 6 decimals
const c = a.add(b); // Error: incompatible amounts

// ✅ Use amounts with same token
const a = Amount.parse("10", STRK);
const b = Amount.parse("5", STRK);
const c = a.add(b); // Works!

​

Transaction Fails in Preflight but Not in Execution

try {
  const tx = await wallet.execute(calls);
  await tx.wait();
} catch (error) {
  // Handle error appropriately
  console.error("Transaction failed:", error);
}

​

TypeScript Type Errors

import { Address, Amount, ChainId } from "starkzap";

// Use fromAddress for addresses
const addr: Address = fromAddress("0x...");

// Use Amount.parse for amounts
const amount: Amount = Amount.parse("10", STRK);

// Use ChainId constants
const chainId = ChainId.MAINNET;

​

Network Configuration Issues

// Check current chain ID
const chainId = wallet.getChainId();
console.log(chainId.toLiteral()); // "SN_MAIN" or "SN_SEPOLIA"

// Verify RPC URL
const provider = sdk.getProvider();
const chainIdFromProvider = await provider.getChainId();

​

Fee Estimation Fails

1. Ensure the account is deployed
2. Verify the calls are valid
3. Check that you have sufficient balance for fees
4. Try using preflight() first to catch call errors

​

Getting More Help

1. Check the API Reference for detailed method signatures
2. Review the Examples for working code samples
3. Ask for help in the Starknet Discord community
4. Browse the Starknet community forum

​

Reporting Issues

1. Check if the issue is already reported
2. Create a detailed issue report with:
   • SDK version
   • Runtime environment (Node.js, browser, React Native)
   • Steps to reproduce
   • Expected vs actual behavior
   • Error messages and stack traces