gatsbyjs/gatsby · error

Could not locate File node for ${mdxPath}

Error message

Could not locate File node for ${mdxPath}

What it means

Thrown by gatsby-plugin-mdx's onCreatePage handler when the page's MDX content path (extracted via getPathToContentComponent) does not match any File node's absolutePath in the Gatsby node store. The plugin needs the File node to read frontmatter and re-create the page with context, so a missing node aborts the per-page processing.

Source

Thrown at packages/gatsby-plugin-mdx/src/gatsby-node.ts:349

  { page, actions, getNodesByType },
  pluginOptions
) => {
  const { createPage, deletePage } = actions
  const { extensions } = defaultOptions(pluginOptions)

  const mdxPath = getPathToContentComponent(page.component)
  const ext = path.extname(mdxPath)

  // Only apply on pages based on .mdx files
  if (!extensions.includes(ext)) {
    return
  }

  const fileNode = getNodesByType(`File`).find(
    node => node.absolutePath === mdxPath
  )
  if (!fileNode) {
    throw new Error(`Could not locate File node for ${mdxPath}`)
  }

  // Avoid loops
  if (!page.context?.frontmatter) {
    const content = await fs.readFile(mdxPath, `utf8`)
    const { frontmatter } = parseFrontmatter(
      fileNode.internal.contentDigest,
      content
    )

    deletePage(page)
    createPage({
      ...page,
      context: {
        ...page.context,
        frontmatter,
      },
    })

View on GitHub (pinned to 8b06340921)

Solutions

1. Confirm the MDX file at mdxPath (printed in the message) still exists on disk.
2. Ensure gatsby-source-filesystem includes the directory containing that MDX so a File node is created.
3. If the path is stale, clear .cache and re-run `gatsby develop`/`build` so pages regenerate from current files.
4. Check for case mismatches between the page component path and the actual filename on disk.

Example fix

// gatsby-config.js — before (MDX dir not sourced)
plugins: [{ resolve: 'gatsby-source-filesystem', options: { name: 'posts', path: 'content/posts' } }]
// after (include the MDX directory referenced by the page)
plugins: [
  { resolve: 'gatsby-source-filesystem', options: { name: 'posts', path: 'content/posts' } },
  { resolve: 'gatsby-source-filesystem', options: { name: 'pages', path: 'src/pages' } },
]

const fileNode = getNodesByType('File').find(n => n.absolutePath === mdxPath)
if (!fileNode) { report.warn(`No File node for ${mdxPath}; skipping page`); return }

const hasFileNode = (mdxPath: string): boolean =>
  !!getNodesByType('File').find(n => n.absolutePath === mdxPath)

When it happens

Trigger: A page whose component string carries __contentFilePath pointing at an MDX file that has no corresponding File node — file was not sourced (no gatsby-source-filesystem covering it), path is stale (file moved/deleted after page creation), or absolutePath casing differs from what the page stores.

Common situations: MDX file deleted or moved after createPage ran but before the page is processed; gatsby-source-filesystem config does not include the directory holding the MDX; path case mismatch on case-sensitive filesystems; symlinked content directories not followed by the source plugin.

Related errors

• ${JSON.stringify(result)}
• The following page component must contain '?__contentFilePat
• RemoteFileNode does not have a mimeType. The field is requir

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