A Next.js Server Action cannot read the values the user submitted
formData.get('email') returns null although the field was filled inShort 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.
Fix it fast
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)) }2Match what you see, then jump to its fix
- 1
The probe prints [ 'FormData' ] but formData.get('email') is nullThe input has no name attributeFix - 2
The probe prints [ 'Object', 'FormData' ]: the first argument is the state, not the formuseActionState put the previous state before the form dataFix - 3
The 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
A 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
- 1
What does the error look like?
formData.get('email') returns null although the field was filled inThe action receives a state object or an id where it expected FormDataObject.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
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=*.tsx2Fix
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 devConfirmed by react.dev
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=*.tsx2Fix
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 devConfirmed by nextjs.org
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
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fixWeb 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 fixWeb 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