Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A Next.js Server Action cannot read the values the user submitted

ErrorformData.get('email') returns null although the field was filled in

Short answer

A Server Action receives a FormData object, and it holds only the inputs that have a name attribute. If formData.get returns null, check the names first. If the value is not FormData at all, an extra argument arrived before it: the previous state from useActionState, or a value added with bind.

  • Applies to Next.js 15, Next.js 16, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the type of every argument the action receives. The result shows whether FormData arrives at all and in which position, which separates the causes below. Put this in a separate actions file and point the form at it for one test.

    // app/actions.ts
    'use server'
    
    export async function probe(...args: unknown[]) {
      console.log(args.length, args.map((a) => (a as object)?.constructor?.name))
    }
  2. 2Match what you see, then jump to its fix

    1. 1The probe prints [ 'FormData' ] but formData.get('email') is nullThe input has no name attributeFix
    2. 2The probe prints [ 'Object', 'FormData' ]: the first argument is the state, not the formuseActionState put the previous state before the form dataFix
    3. 3The probe prints [ 'String', 'FormData' ] for an action that was passed through .bind(null, id)A value added with bind arrives before the form dataFix
    4. 4A check over the whole object fails, or a row gets extra columns, while every field is filled inObject.fromEntries(formData) returns more keys than the fieldsFix

What does the error look like?

  • formData.get('email') returns null although the field was filled in
  • The action receives a state object or an id where it expected FormData
  • Object.fromEntries(formData) contains keys that start with $ACTION_

Cause 1 of 4

The input has no name attribute

1Check

React includes only inputs that have a name attribute in the FormData it passes to the action. Ask the browser which names the form would send, and compare them with the keys the action reads.

[...new FormData(document.querySelector('form')).keys()]

2Fix

Give every field a name and read exactly that string. An id, a label or a React state variable does not put a value into FormData.

<form action={createInvoice}>
  <input type="text" name="customerId" />
  <input type="number" name="amount" />
  <button type="submit">Save</button>
</form>

3Verify

Submit the form once and print the keys on the server. The terminal that runs next dev should list both field names.

'use server'

export async function createInvoice(formData: FormData) {
  console.log(Array.from(formData.keys()))
}

Confirmed by react.dev

Did this fix it?

Cause 2 of 4

useActionState put the previous state before the form data

1Check

useActionState calls the action with the previous state first (the initial state on the first submit) and the submitted form data second. An action still written as (formData) reads the state object as if it were the form.

grep -rn "useActionState" app components --include=*.tsx

2Fix

Add a first parameter for the previous state and read the form from the second one.

// app/actions.ts
'use server'

export async function createUser(
  prevState: { message: string },
  formData: FormData,
) {
  const email = formData.get('email')
  return { message: email ? 'Saved' : 'Email is required' }
}

// component: const [state, formAction, pending] = useActionState(createUser, { message: '' })

3Verify

Submit the form. The returned message shows in the component and the terminal has no TypeError.

npm run dev

Confirmed by react.dev

Did this fix it?

Cause 3 of 4

A value added with bind arrives before the form data

1Check

Values bound to the action are passed first and the FormData comes after them. Look for bind calls on the function that the form uses.

grep -rn "\.bind(null" app components --include=*.tsx

2Fix

Declare the bound parameters first and formData last. A hidden input also works, but its value is part of the rendered HTML.

// app/actions.ts
'use server'

export async function updateUser(userId: string, formData: FormData) {
  const name = formData.get('name')
}

// component
const updateUserWithId = updateUser.bind(null, userId)
// <form action={updateUserWithId}>

3Verify

Submit the form and print userId and the name field in the action.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

Object.fromEntries(formData) returns more keys than the fields

1Check

Print the object. Next.js documents that the result of Object.fromEntries(formData) carries extra properties whose names start with $ACTION_.

console.log(Object.fromEntries(formData))

2Fix

Read the fields you expect one by one, as the Next.js forms guide does before validation. If you must loop over entries, skip the keys that start with $ACTION_.

const raw = {
  customerId: formData.get('customerId'),
  amount: formData.get('amount'),
}

// or, when the field list is dynamic
const fields = Object.fromEntries(
  Array.from(formData.entries()).filter(([key]) => !key.startsWith('$ACTION_')),
)

3Verify

Print raw or fields after a submit. It should hold only your own field names.

console.log(raw)

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Give each form control a name when you write the markup, and read that same string in the action.
  • Type the parameters, (formData: FormData) or (prevState: State, formData: FormData), so a wrong order shows up in the editor.
  • Validate on the server with a schema built from the named fields, as the Next.js forms guide shows, instead of trusting client checks.
  • Check the user's session inside each Server Action, even when the page that shows the form is already protected.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

next/link throws React.Children.only on its children

Error: React.Children.only expected to receive a single React element child.

React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.

3 causes, each with a fix

Web apps

Hydration failed after adding next-themes dark mode

Console reports a server and client mismatch on the html element

next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.