gatsbyjs/gatsby · error · Error

createNodeId must be a function, was ${typeof createNodeId}

Error message

createNodeId must be a function, was ${typeof createNodeId}

What it means

Thrown by createFileNodeFromBuffer in gatsby-source-filesystem when the createNodeId parameter is not a function. This is a defensive validation — createNodeId must be a Gatsby-provided helper that generates deterministic node IDs. Passing anything else (string, undefined, object) breaks node creation.

Source

Thrown at packages/gatsby-source-filesystem/src/create-file-node-from-buffer.js:133

 * @param {CreateFileNodeFromBufferPayload} options
 * @return {Promise<Object>}                  Returns the created node
 */
module.exports = ({
  buffer,
  hash,
  cache,
  createNode,
  getCache,
  parentNodeId = null,
  createNodeId,
  ext,
  name,
}) => {
  // validation of the input
  // without this it's notoriously easy to pass in the wrong `createNodeId`
  // see gatsbyjs/gatsby#6643
  if (typeof createNodeId !== `function`) {
    throw new Error(
      `createNodeId must be a function, was ${typeof createNodeId}`
    )
  }
  if (typeof createNode !== `function`) {
    throw new Error(`createNode must be a function, was ${typeof createNode}`)
  }
  if (typeof getCache === `function`) {
    // use cache of this plugin and not cache of function caller
    cache = getCache(`gatsby-source-filesystem`)
  }
  if (typeof cache !== `object`) {
    throw new Error(
      `Neither "cache" or "getCache" was passed. getCache must be function that return Gatsby cache, "cache" must be the Gatsby cache, was ${typeof cache}`
    )
  }

  if (!buffer) {
    return Promise.reject(`bad buffer: ${buffer}`)

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass the createNodeId function from the Gatsby Node API (destructured from the first argument or actions.createNodeId).
2. Ensure createNodeId is invoked at call-time: createNodeId('some-id'), not passed as a string.
3. Check the function signature matches the documented parameters.
4. Verify you're destructuring from the correct Gatsby helper object.

Example fix

// before
await createFileNodeFromBuffer({ buffer, name: 'file', createNodeId: 'my-id' })
// after
await createFileNodeFromBuffer({ buffer, name: 'file', createNodeId })
// where createNodeId is from: const { createNodeId } = actions

// Ensure createNodeId is a function before calling
if (typeof createNodeId !== 'function') {
  throw new TypeError(`createNodeId must be a function, got ${typeof createNodeId}`)
}

const isCreateNodeId = (val: unknown): val is (id: string) => string =>
  typeof val === 'function'

When it happens

Trigger: typeof createNodeId !== 'function' because the caller passed a string ID, undefined, or destructured incorrectly from the Gatsby API (e.g., forgot to pass it from actions/Helpers).

Common situations: A plugin or gatsby-node.js calls createFileNodeFromBuffer but passes a raw string instead of the createNodeId function from createNodeId helper, or destructures the wrong variable name.

Related errors

• createNode must be a function, was ${typeof createNode}
• PageCreator: To query node "gatsbyPath" the "filePath" argum
• Invalid plugin options for "gatsby-plugin-sitemap":
• The "layout" argument is required for "${source.url}"
• Either the "width" or "height" argument is required f

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/3f0cdaa317e950ac. Report an issue: GitHub.