Error Handling

Overview

This guide covers common authentication errors, implementation of error boundaries, and best practices for handling errors in your application. Understanding these concepts is crucial for building robust and user-friendly authentication flows.

Common Errors

When implementing authentication, you may encounter several typical error scenarios. Here's how to handle the most frequent cases:

Popup Blocked

Occurs when the browser blocks the authentication popup window. Common in situations where popup blockers are enabled.

try {
  await auth.signIn();
} catch (error) {
  if (error.code === 'popup_blocked') {
    // Handle popup blocked
  }
}

Network Errors

Happens when there are connectivity issues preventing the authentication request from completing.

try {
  await auth.signIn();
} catch (error) {
  if (error.code === 'network_error') {
    // Handle network issues
  }
}

Authentication Cancelled

Triggered when users manually cancel the authentication process.

try {
  await auth.signIn();
} catch (error) {
  if (error.code === 'auth_cancelled') {
    // Handle user cancellation
  }
}

Error Boundaries

Error Boundaries are React components that catch JavaScript errors anywhere in their child component tree and display fallback UI instead of crashing the application.

class AuthErrorBoundary extends React.Component {
  state = { hasError: false, error: null };
 
  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }
 
  render() {
    if (this.state.hasError) {
      return <ErrorDisplay error={this.state.error} />;
    }
 
    return this.props.children;
  }
}

Best Practices

Follow these guidelines to implement robust error handling:

1. Always implement error handling

   • Catch and handle all potential errors
   • Never leave try-catch blocks empty

2. Use appropriate error boundaries

   • Implement error boundaries at strategic points
   • Provide meaningful fallback UI

3. Provide user feedback

   • Display clear error messages
   • Offer guidance on how to resolve issues
   • Use user-friendly language

4. Log errors appropriately

   • Implement comprehensive error logging
   • Include relevant context and stack traces
   • Consider privacy when logging user data

5. Implement retry mechanisms

   • Use exponential backoff for retries
   • Set maximum retry limits
   • Handle permanent failures gracefully

Example Implementation

Below is a complete example showing how to implement these practices in a login component:

function LoginComponent() {
  const [error, setError] = useState<Error | null>(null);
  const [retries, setRetries] = useState(0);
  const { signIn } = useReclaimAuth();
 
  const handleLogin = async () => {
    try {
      setError(null);
      await signIn();
    } catch (err) {
      setError(err);
      
      // Handle specific errors
      if (err.code === 'popup_blocked') {
        alert('Please enable popups for this site');
      } else if (err.code === 'network_error' && retries < 3) {
        setRetries(r => r + 1);
        // Implement exponential backoff
        setTimeout(handleLogin, Math.pow(2, retries) * 1000);
      } else if (err.code === 'auth_cancelled') {
        // User cancelled, no need for error display
        setError(null);
      }
    }
  };
 
  if (error) {
    return (
      <div className="error-container">
        <p>Error: {error.message}</p>
        <button onClick={handleLogin}>Try Again</button>
      </div>
    );
  }
 
  return <button onClick={handleLogin}>Sign In</button>;
}

Troubleshooting Tips

• Always check browser console for detailed error messages
• Verify network connectivity when authentication fails
• Ensure popup blockers are disabled for authentication flows
• Monitor retry attempts and implement appropriate timeout periods