Error Handling in Actions
Implement effective error handling strategies within Server Actions to provide robust feedback to users.
Error Handling in Actions is a free Next.js 15 Fullstack (App Router + Server Actions) lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Next.js 15 Fullstack (App Router + Server Actions) learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Robust Server Actions
When building applications, things can go wrong! Data might be invalid, a database might be unreachable, or an external API could fail.
Effective error handling in Server Actions is crucial for a smooth user experience and maintaining data integrity. It prevents crashes and provides clear feedback.
The `try-catch` Block
In JavaScript/TypeScript, the fundamental way to handle potential errors is using a try-catch block. It allows you to 'try' executing code and 'catch' any errors that occur.
- Code inside the
tryblock is executed. - If an error occurs, execution jumps to the
catchblock. - The
catchblock receives the error object, allowing you to handle it gracefully.
Server Action Error Example
Let's look at a simple Server Action that might fail. Imagine an action that divides two numbers, but one could be zero.
Without error handling, a division by zero would crash the action and potentially the client-side form submission.
export async function divideNumbers(formData: FormData) {
const num1 = Number(formData.get('num1'));
const num2 = Number(formData.get('num2'));
if (num2 === 0) {
throw new Error('Cannot divide by zero!');
}
const result = num1 / num2;
return { success: true, result };
}Catching Errors on the Server
To prevent the action from crashing, we wrap the risky code in a try-catch block. This allows us to log the error on the server and prevent sensitive error details from reaching the client.
export async function divideNumbers(formData: FormData) {
try {
const num1 = Number(formData.get('num1'));
const num2 = Number(formData.get('num2'));
if (num2 === 0) {
throw new Error('Cannot divide by zero!');
}
const result = num1 / num2;
return { success: true, result };
} catch (error: any) {
console.error('Action Error:', error.message); // Log on server
// Do NOT return `error` object directly to client!
return { success: false, error: 'An unexpected error occurred.' };
}
}Returning Client-Friendly Errors
After catching an error on the server, we need to return a meaningful, client-friendly message. This message helps users understand what went wrong without exposing internal server details.
- Return an object with a
success: falseflag. - Include an
errorproperty with a user-friendly message. - Avoid sending raw error stack traces to the client for security.
Action with Client Error Return
Here's how our divideNumbers action looks when returning specific error messages to the client:
Notice how different errors get different messages, and a generic message is used for unexpected errors.
export async function divideNumbers(formData: FormData) {
try {
const num1 = Number(formData.get('num1'));
const num2 = Number(formData.get('num2'));
if (isNaN(num1) || isNaN(num2)) {
throw new Error('Invalid input: Please enter numbers.');
}
if (num2 === 0) {
throw new Error('Division by zero is not allowed.');
}
const result = num1 / num2;
return { success: true, result };
} catch (error: any) {
console.error('Server Action Failed:', error.message);
return { success: false, error: error.message || 'Unknown error occurred.' };
}
}Client-Side Error Display
On the client, after calling a Server Action, you'll receive the returned object. You can then check the success and error properties to update your UI.
This allows you to show an error message to the user, disable parts of the form, or take other corrective actions.
import { useState } from 'react';
import { divideNumbers } from './actions'; // Your Server Action
export default function CalculatorForm() {
const [message, setMessage] = useState('');
async function handleSubmit(formData: FormData) {
const res = await divideNumbers(formData);
if (res.success) {
setMessage(`Result: ${res.result}`);
} else {
setMessage(`Error: ${res.error}`);
}
}
return (
<form action={handleSubmit}>
<input type="number" name="num1" />
<input type="number" name="num2" />
<button type="submit">Calculate</button>
{message && <p>{message}</p>}
</form>
);
}React `useFormState` Hook
For forms, React's useFormState hook is specifically designed to manage state returned by a Server Action. It simplifies displaying feedback (like success or error messages) after a form submission.
It takes your action and an initial state, and returns the current state and an updated action that you pass to your <form>'s action prop.
Using `useFormState` for Errors
Here's how to integrate useFormState to display error messages directly within your form component. It makes handling the action's response very clean.
import { useFormState } from 'react-dom';
import { divideNumbers } from './actions';
const initialState = { success: false, error: '', result: null };
export default function CalculatorForm() {
const [state, formAction] = useFormState(divideNumbers, initialState);
return (
<form action={formAction}>
<input type="number" name="num1" placeholder="Number 1" />
<input type="number" name="num2" placeholder="Number 2" />
<button type="submit">Calculate</button>
{state.success && <p>Result: {state.result}</p>}
{!state.success && state.error && <p style={{ color: 'red' }}>{state.error}</p>}
</form>
);
}Handling Server Action Errors
Which of the following is the BEST practice for handling errors caught within a Next.js Server Action?
Recap: Error Handling
You've mastered error handling in Next.js Server Actions!
- Use
try-catchblocks to gracefully handle errors on the server. - Log server-side errors for debugging and monitoring.
- Return client-friendly error messages using a structured object (e.g.,
{ success: false, error: 'message' }). - Utilize React's
useFormStatehook to easily manage and display action results and errors in your forms.
Robust error handling makes your applications more reliable and user-friendly!
Frequently asked questions
Is the “Error Handling in Actions” lesson free?
Yes — the full text of “Error Handling in Actions” is free to read here on the web, and the Next.js 15 Fullstack (App Router + Server Actions) course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Next.js 15 Fullstack (App Router + Server Actions) course, upgrade to CoddyKit PRO.
What will I learn in “Error Handling in Actions”?
Implement effective error handling strategies within Server Actions to provide robust feedback to users. You practise Next.js 15 Fullstack (App Router + Server Actions) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Next.js 15 Fullstack (App Router + Server Actions)?
No prior experience is required. Next.js 15 Fullstack (App Router + Server Actions) on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Error Handling in Actions” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Next.js 15 Fullstack (App Router + Server Actions) lesson?
Yes. Every Next.js 15 Fullstack (App Router + Server Actions) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.