Skip to main content

​
Error Categories

CategoryExamples
AuthenticationOAuth failed, invalid credentials, email not verified
SessionSession expired, no session found, nonce mismatch
WalletAccount not deployed, insufficient funds
TransactionExecution failed, paymaster error
NetworkRPC errors, timeout
LimitsMAU exceeded

​
Authentication Errors

​
Email Not Verified (Firebase)

When a user tries to login before verifying their email: 
import { useCavos } from '@cavos/react';

try {
  await login('firebase', { email, password });
} catch (error) {
  if (error.name === 'EmailNotVerifiedError') {
    console.log('Unverified email:', error.email);
    showResendVerificationButton(error.email);
  }
}

​
Invalid Credentials (Firebase)

try {
  await login('firebase', { email, password });
} catch (error) {
  if (error.message?.includes('auth/wrong-password')) {
    showMessage('Invalid email or password');
  } else if (error.message?.includes('auth/user-not-found')) {
    showMessage('No account found with this email');
  } else if (error.message?.includes('auth/invalid-email')) {
    showMessage('Please enter a valid email address');
  }
}

​
Email Already Registered

try {
  await register('firebase', { email, password });
} catch (error) {
  if (error.error === 'Email already registered and verified') {
    showMessage('This email is already registered. Please login.');
  }
}

​
OAuth Failed (Google/Apple)

try {
  await login('google');
} catch (error) {
  if (error.message.includes('popup')) {
    showMessage('Please allow popups for authentication');
  } else if (error.message.includes('cancelled')) {
    showMessage('Login cancelled');
  } else if (error.message.includes('nonce')) {
    // Nonce mismatch - session state corrupted
    showMessage('Authentication error. Please try again.');
  }
}

​
Session Errors

​
No Session Found

When trying to execute transactions without a valid session: 
try {
  await execute(calls);
} catch (error) {
  if (error.message.includes('No session') || 
      error.message.includes('not initialized')) {
    // Re-authenticate
    await login('google');
  }
}

​
Session Expired

Session has exceeded its maxBlock: 
try {
  await execute(calls);
} catch (error) {
  if (error.message.includes('Session expired') ||
      error.message.includes('expired')) {
    // Renew the session with fresh JWT
    await renewSession();
    // Retry the operation
    await execute(calls);
  }
}

​
JWT Nonce Mismatch

Happens if session state was corrupted or replayed: 
try {
  await handleCallback(authData);
} catch (error) {
  if (error.message.includes('nonce')) {
    // Clear corrupted state and retry
    sessionStorage.clear();
    await login('google');
  }
}

​
Email Verification Errors

​
Rate Limited

try {
  await cavos.resendVerificationEmail(email);
} catch (error) {
  if (error.error === 'rate_limited') {
    showMessage(`Please wait ${error.wait_seconds} seconds before trying again`);
  }
}

​
Already Verified

try {
  await cavos.resendVerificationEmail(email);
} catch (error) {
  if (error.error === 'already_verified') {
    showMessage('Your email is already verified! You can login now.');
  }
}

​
Verification Token Expired

// Handle in your callback page
const searchParams = new URLSearchParams(window.location.search);
if (searchParams.get('status') === 'error') {
  const message = searchParams.get('message');
  if (message?.includes('expired')) {
    showMessage('Verification link expired. Request a new one.');
  }
}

​
Wallet Errors

​
Account Not Deployed

try {
  await execute(calls);
} catch (error) {
  if (error.message.includes('not deployed')) {
    // Deploy the account first
    await deployAccount();
    await execute(calls);
  }
}
In most cases, account deployment happens automatically on first transaction. This error typically means the first transaction failed.

​
Address Seed Mismatch

Happens when the salt or identity doesn’t match expected values: 
try {
  await handleCallback(authData);
} catch (error) {
  if (error.message.includes('Address seed mismatch')) {
    // Identity verification failed - clear and retry
    await logout();
    await login('google');
  }
}

​
MAU Limit Exceeded

try {
  await login('google');
} catch (error) {
  if (error.message.includes('MAU limit')) {
    showMessage('App has reached its user limit. Please try later or upgrade plan.');
  }
}

​
Transaction Errors

​
Paymaster Error

try {
  await execute(calls);
} catch (error) {
  if (error.message.includes('paymaster')) {
    showMessage('Transaction sponsorship failed. Please try again.');
  }
}

​
Contract Error

try {
  await execute(calls);
} catch (error) {
  // Common Starknet errors
  if (error.message.includes('Contract not found')) {
    showMessage('Contract does not exist on this network');
  } else if (error.message.includes('Entry point not found')) {
    showMessage('Function does not exist on this contract');
  } else if (error.message.includes('insufficient')) {
    showMessage('Insufficient balance for this operation');
  }
}

​
Network Errors

​
RPC Timeout

try {
  await execute(calls);
} catch (error) {
  if (error.message.includes('timeout') || 
      error.message.includes('network')) {
    showMessage('Network error. Please try again.');
  }
}

​
Custom RPC

If hitting rate limits on default RPC: 
const config = {
  appId: 'your-app-id',
  starknetRpcUrl: 'https://your-own-rpc.com',  // Use your own RPC
};

​
Debugging

​
Enable Logging

<CavosProvider config={{
  appId: 'your-app-id',
  enableLogging: true,  // Shows SDK debug logs
}}>

​
Check Wallet State

const { isAuthenticated, address, walletStatus } = useCavos();

console.log('Address:', address);
console.log('Authenticated:', isAuthenticated);
console.log('Wallet status:', walletStatus);
// { isDeploying, isDeployed, isRegistering, isSessionActive, isReady }

​
Error Recovery Flow

async function handleError(error: Error): { action: string; message: string } {
  // User action needed
  if (error.message.includes('cancelled')) {
    return { action: 'retry', message: 'Please complete authentication' };
  }
  
  // Session issues
  if (error.message.includes('expired') || error.message.includes('No session')) {
    return { action: 'reauth', message: 'Session expired. Please login again.' };
  }
  
  // App limit
  if (error.message.includes('MAU limit')) {
    return { action: 'wait', message: 'App limit reached' };
  }
  
  // Network issue
  if (error.message.includes('network') || error.message.includes('timeout')) {
    return { action: 'retry', message: 'Network error. Retrying...' };
  }
  
  // Unknown error
  console.error('Unhandled error:', error);
  return { action: 'support', message: 'An error occurred. Please contact support.' };
}