Debugging & Error Resolution

This guide covers the most common errors you'll encounter when building with Chipi and how to fix them. Errors fall into six categories: wallet, transaction, session key, address, calldata encoding, and webhook. For interactive debugging, use the debug_error MCP tool which pattern-matches your error against a database of 40+ known issues.

"Wallet not found". The user hasn't created a wallet yet, or the externalUserId doesn't match. Check hasWallet from useChipiWallet. If false, show the wallet creation UI.

"User not authenticated". The auth provider doesn't have an active session. Ensure your auth provider (Clerk/Firebase/Supabase) wraps the app and the user is signed in. ChipiProvider must be inside the auth provider.

"NotAllowedError" / "Passkey denied". The user cancelled the biometric prompt. Show a retry message. Don't auto-retry. Wait for user action.

"PRF not supported". The device doesn't support the WebAuthn PRF extension needed for passkey encryption. Call isPRFSupported() to check before offering passkey auth. Fall back to PIN if not available.

"InvalidStateError" / "Ceremony in progress". Multiple passkey prompts triggered simultaneously. Debounce wallet creation and signing calls.

"Insufficient balance". The wallet doesn't have enough tokens. Check balance with useGetTokenBalance before transferring. Ensure you're checking the correct token (USDC vs ETH vs STRK).

"Invalid address". Not a valid StarkNet address. Must be 0x + 64 hex characters. Common mistakes: EVM address (40 chars instead of 64), Solana address (Base58), missing 0x prefix, or leading zeros stripped.

"Execution failed" / "Reverted". The transaction was reverted on-chain. Check the transaction on Starkscan (starkscan.co/tx/{hash}) for the revert reason. Common causes: wrong calldata encoding, missing token approval, or contract access control.

"Invalid API key" / 401. Check .env.local. The key should start with pk_prod_ for public operations. Get a valid key from dashboard.chipipay.com.

"Rate limit" / 429. More than 100 requests per minute. Implement request throttling or debouncing.

"Session keys require CHIPI wallet". Session keys only work with walletType: "CHIPI". If the wallet was created with "READY" (Argent X), session keys are not available. Create a new CHIPI wallet.

"Session expired". The session key exceeded its expiry timestamp. Create and register a new session key. Check hasActiveSession before executing.

"No remaining calls". All allowed calls for this session have been used. Monitor remainingCalls and prompt re-registration when low.

"Session not registered". The on-chain registration failed. If the wallet has never transacted, make any transaction first (wallet deployment happens on first tx), then register.

"Method not allowed". The called method wasn't included in allowedMethods during session creation. Create a new session key with the correct methods.

StarkNet, EVM, and Solana use different address formats. Mixing them up is a common error:

• - StarkNet: 0x + 64 hex characters. Regex: /^0x[0-9a-fA-F]{64}$/
• - EVM (Ethereum): 0x + 40 hex characters. If you see this, the user has an Ethereum address, not StarkNet
• - Solana: Base58 encoded, 32-44 characters, no 0x prefix

Common address issues:

• - Leading zeros stripped (0x49d365... with 63 hex chars). Pad with zeros after 0x
• - Missing 0x prefix. Prepend 0x
• - Trailing whitespace. Call .trim()
• - EVM address used for StarkNet. Different chains, different formats

When using useCallAnyContract, calldata must be encoded correctly:

u256 encoding. StarkNet's u256 is two felt252 values: [low_128_bits, high_128_bits]. For values under 2^128 (virtually all practical amounts): [amount.toString(), "0"].

Common mistakes:

• - Single value instead of [low, high]. ["10000000"] should be ["10000000", "0"]
• - Human-readable amount in raw calldata. 10 USDC is "10000000" (10 * 10^6), not "10"
• - JavaScript number precision loss. Use strings for large numbers: "1000000000000000000"
• - Wrong argument order. Must match the contract ABI exactly
• - Missing array length prefix. Arrays need ["3", "100", "200", "300"], not ["100", "200", "300"]

Note: useTransfer handles decimal conversion automatically. Only useCallAnyContract requires raw calldata.

If no specific error matches, run through this checklist:

1. SDK installed?. Check @chipi-stack/nextjs in package.json
2. Provider wrapping app?. ChipiProvider in layout.tsx
3. Auth configured?. Clerk/Firebase/Supabase wrapping the app
4. Env vars set?. NEXT_PUBLIC_CHIPI_API_KEY starts with pk_prod_
5. User signed in?. Auth provider shows authenticated state
6. Wallet exists?. hasWallet from useChipiWallet is true
7. Wallet type correct?. CHIPI for session keys, READY for Argent X
8. Addresses valid?. Match /^0x[0-9a-fA-F]{64}$/
9. Amounts valid?. Positive, correct format for the hook
10. Check browser console. Look for additional error details

For webhook verification: use request.text() (not .json()) before computing HMAC. Use the sk_prod_ key (not pk_prod_).