Maaz Zindani

Loading the index…

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

Error serializing props returned from getStaticProps

ErrorError serializing `.post.publishedAt` returned from `getStaticProps` in "/blog/[slug]".

Short answer

Next.js checks that everything in props can be written as JSON. The check rejects undefined, Date objects, class instances, functions and circular references. Find the path named in the error, then replace undefined with null or drop the key, turn dates into ISO strings, and pass plain objects only.

  • Applies to Next.js 15, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the path in the first line of the error (for example .post.publishedAt). It names the exact key. Then print that value and its type in getStaticProps.

    // inside getStaticProps, just before the return
    console.log(typeof post.publishedAt, post.publishedAt)
  2. 2Match what you see, then jump to its fix

    1. 1Reason: `undefined` cannot be serialized as JSON. Please use `null` or omit this value.A prop is undefinedFix
    2. 2cannot be serialized as JSON. Please only return JSON serializable data types. (the message ends with the object type, such as [object Date])A Date object (or another class instance) is in propsFix
    3. 3Circular references cannot be expressed in JSONA function, bigint, symbol or circular object is returnedFix

What does the error look like?

  • Error serializing `.post.publishedAt` returned from `getStaticProps` in "/blog/[slug]".
  • Reason: `undefined` cannot be serialized as JSON. Please use `null` or omit this value.
  • cannot be serialized as JSON. Please only return JSON serializable data types.

Cause 1 of 3

A prop is undefined

1Check

Optional fields from a database row, a CMS or a markdown front matter block come back as undefined when they are empty. JSON has no undefined, so Next.js stops the build instead of silently dropping the key.

// list every key that is undefined
Object.entries(post).filter(([, v]) => v === undefined).map(([k]) => k)

2Fix

Give the field a null fallback, or leave the key out when it is empty.

return {
  props: {
    post: {
      ...post,
      subtitle: post.subtitle ?? null,
    },
  },
}

3Verify

Run the build. The page should be generated without the serialization error.

npx next build

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

A Date object (or another class instance) is in props

1Check

Only plain objects and arrays are accepted. A Date is a class instance, so it fails even though JSON.stringify could print it. Date columns and parsed front matter are common sources.

console.log(Object.prototype.toString.call(post.publishedAt))

2Fix

Convert the value to a string or a number in getStaticProps, and build the Date again inside the component if you need one.

// getStaticProps
return {
  props: { post: { ...post, publishedAt: post.publishedAt.toISOString() } },
}

// component
const date = new Date(post.publishedAt)

3Verify

Rebuild and open the page.

npx next build

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

A function, bigint, symbol or circular object is returned

1Check

The check rejects functions, bigint, symbol and circular references, because none of these can be expressed as JSON. Whole records from a database client sometimes carry one of them.

console.log(Object.keys(row), typeof row.id)

2Fix

Return a plain object with only the fields the page shows. For a bigint, send a string.

const plain = {
  id: row.id.toString(),   // bigint -> string
  title: row.title,
}
return { props: { post: plain } }

3Verify

Rebuild; a clean build means props are plain data.

npx next build

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Map database or CMS records to a small plain object before returning them from getStaticProps.
  • Type the props with GetStaticProps so optional fields are written as string | null, not as optional keys.
  • Store dates as ISO strings in the page props and parse them only where they are shown.

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.js: only plain objects can be passed to Client Components

Only plain objects, and a few built-ins, can be passed to Client Components from Server Components. Classes or null prototypes are not supported.

Props from a Server Component to a Client Component must be serializable.

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.