Stop Throwing Errors in Next.js Server Actions (Well… Sometimes)

We all love a good throw new Error(), right? But in Next.js server actions, that innocent line can sometimes become a silent troublemaker — especially in production!

😬 The Problem

When you do this:

throw new Error('Something went wrong') // ❌ Bad

you might notice… sometimes the error just disappears. No message. No clue. Nothing. 🤷‍♀️

Here’s why: When your server sends something to the browser, Next.js needs to convert it into plain text or JSON so it can travel through the network.

That conversion is called serialization.

But…. JavaScript Error objects have a bunch of hidden technical info inside (like stack traces and internal links) — and those parts can’t be converted properly.

So when Next.js tries to send the error to the client, it basically goes:

“Oops, I don’t know how to send this thing… I’ll just skip it.”

And that’s how your error details vanish into thin air 💨

💡 The Better Way

Instead of throwing, return a simple object that you can safely send and display:

try {
  const user = await getUser()
  return { success: true, data: user }
} catch (error) {
  return {
    success: false,
    error: error instanceof Error ? error.message : 'Something went wrong',
  }
}

This way, you:

• Keep full control of what reaches the UI
• Always get readable messages
• Avoid those mysterious “nothing happened” errors

🚨 When Throwing Is Okay

Sometimes you should throw — like when your app can’t continue:

// Example 1: Config is missing
if (!process.env.DATABASE_URL) {
  throw new Error('Database not configured')
}

// Example 2: Unauthorized user
if (!isAuthorized) {
  throw new Error('Unauthorized')
}

Throwing makes sense when something is fundamentally broken, not just when something went wrong.

💭 TL;DR

SituationWhat to DoRegular app or API error✅ Return { success, error }Critical crash (should stop everything)💥 Throw an error

🌸 Wrap-Up

So yeah, in Next.js server actions — Throw only when you want a crash, not when you want clarity. Returning clean objects keeps your UI happy and your users even happier 💖