Next.js Server Actions: Diagnosing Form Submission and Revalidation Issues

Problem: Next.js Server Actions Not Submitting or Revalidating

If your Next.js Server Actions fail to submit forms, skip revalidation, or throw errors, the cause usually falls into a few recognizable patterns. This guide helps you identify the condition, verify it, and apply the matching fix.

Recognizable Conditions

• Form submits but no server code runs
• Page does not update after form submission
• 403 or 401 errors on form submission
• TypeScript errors when importing server actions
• ReferenceError for Node.js globals in edge runtime

Diagnostic Table

Symptom	Most Likely Cause	Verification Step
Form submits but no server code runs	Server action not attached to form action prop	Open DevTools Network tab and check for POST to /action
Page does not update after submission	Missing or incorrect revalidatePath() call	Confirm revalidatePath('/path') runs after the mutation
403 or 401 errors on submission	CSRF token validation failing due to session or cookie issues	Check Application > Cookies for the session cookie
TypeScript errors about server actions	Action imported in a client component or wrong file location	Ensure the action is defined and imported from a server component
ReferenceError: process is not defined	Node.js globals used in edge runtime	Replace process.env with process.env.NEXT_PUBLIC_*

Ordered Diagnostic Checks

1. Check Next.js and React versions

   Run in the project root:

   npx next --version

   Server Actions require Next.js 13.4+ and React 18.2+. If versions are lower, update dependencies in package.json and reinstall.

2. Inspect the form implementation

   Pass the server action directly to the form's action prop:

   <form action={submitContact}>
     <input name="email" />
     <button type="submit">Send</button>
   </form>

   Do not wrap the action in an event handler or assign it to onSubmit unless you are intentionally bypassing the Server Actions flow.

3. Inspect network requests

   Open DevTools, go to the Network tab, and submit the form. Look for:

   • Request URL: /action
   • Request Method: POST
   • Request Payload: encrypted body containing form fields

   If no request appears, the form is not wired to the action.

4. Verify revalidation behavior

   Add explicit revalidation after the mutation:

   import { revalidatePath } from 'next/cache'
   
   export async function submitContact(formData) {
     const email = formData.get('email')
     await db.message.create({ data: { email } })
     revalidatePath('/contact/success')
   }

   Reload the target page and confirm the new data appears without a manual refresh.

5. Check CSRF and session cookies

   Server Actions use encrypted tokens tied to session cookies. Verify:

   • The session cookie exists in Application > Cookies
   • The cookie uses HttpOnly and Secure flags in production
   • No mixed-content warnings on HTTPS pages

6. Validate TypeScript configuration

   Server actions must be defined in server components. Importing them into client components causes type errors. Keep action definitions in files that are not marked with 'use client'.

Fixes Based on Findings

Fix: Attach the Action to the Form

Define the action in a server component and pass it to action:

// app/components/ContactForm.tsx
import { revalidatePath } from 'next/cache'

export async function submitContact(formData: FormData) {
  const email = formData.get('email') as string
  await db.message.create({ data: { email } })
  revalidatePath('/contact/success')
}

export default function ContactForm() {
  return (
    <form action={submitContact}>
      <input name="email" type="email" required />
      <button type="submit">Send</button>
    </form>
  )
}

Fix: Add Missing Revalidation

Call revalidatePath() for every route that displays the mutated data:

import { revalidatePath } from 'next/cache'

export async function updateProfile(formData: FormData) {
  const name = formData.get('name') as string
  await db.user.update({
    where: { id: getCurrentUserId() },
    data: { name }
  })
  revalidatePath('/profile')
  revalidatePath('/')
}

Fix: Edge Runtime Globals

Edge runtime does not support Node.js globals such as process. Use build-time constants or NEXT_PUBLIC_* variables:

// Not supported in edge
const port = process.env.PORT

// Edge-compatible
const port = Number(process.env.NEXT_PUBLIC_PORT || 3000)

Escalation Criteria

Escalate to deeper investigation if:

• Network tab shows a successful POST but server logs contain no action execution
• CSRF errors persist despite valid session cookies
• TypeScript errors continue after verifying imports are server-only
• Multiple forms on one page interfere with each other's state

Verification Checklist

1. Form submits via POST to /action
2. Encrypted payload contains all form fields
3. Server action executes without throwing
4. revalidatePath() triggers the expected page update
5. Session cookie remains intact after submission
6. No TypeScript compilation errors