gatsbyjs/gatsby · error

Please install gatsby-source-filesystem

Error message

Please install gatsby-source-filesystem

What it means

Inside createImageNode (image-processing.ts:39-46), the plugin dynamically requires 'gatsby-source-filesystem/create-file-node' to call createFileNode. If the require fails (module not found), the catch block calls reporter.panic. This means gatsby-source-filesystem is not installed in the project, yet gatsby-plugin-image's static image processing needs it to turn a local file path into a Gatsby File node.

Source

Thrown at packages/gatsby-plugin-image/src/node-apis/image-processing.ts:45

  reporter,
}: {
  fullPath: string
  createNodeId: ParentSpanPluginArgs["createNodeId"]
  createNode: Actions["createNode"]
  reporter: Reporter
}): Promise<FileSystemNode | undefined> {
  if (!fs.existsSync(fullPath)) {
    return undefined
  }

  let file: FileSystemNode
  try {
    const {
      createFileNode,
    } = require(`gatsby-source-filesystem/create-file-node`)
    file = await createFileNode(fullPath, createNodeId, {})
  } catch (e) {
    reporter.panic(`Please install gatsby-source-filesystem`)
    return undefined
  }

  if (!file) {
    return undefined
  }

  file.internal.type = `StaticImage`

  createNode(file)

  return file
}

export const isRemoteURL = (url: string): boolean =>
  url.startsWith(`http://`) || url.startsWith(`https://`)

export async function writeImages({

View on GitHub (pinned to 8b06340921)

Solutions

1. Install the package: npm install gatsby-source-filesystem (or yarn add)
2. Ensure gatsby-source-filesystem is listed in gatsby-config.js plugins array
3. If in a monorepo, verify node_modules resolution: run npm ls gatsby-source-filesystem

Example fix

// before: package.json missing the dependency
// after: add to package.json
dependencies: {
  "gatsby-source-filesystem": "^4.0.0",
}

// gatsby-config.js
plugins: [
  `gatsby-plugin-image`,
  {
    resolve: `gatsby-source-filesystem`,
    options: { name: `images`, path: `${__dirname}/src/images` },
  },
]

// Pre-build check: verify gatsby-source-filesystem is installed
try {
  require.resolve('gatsby-source-filesystem')
} catch {
  console.error('gatsby-source-filesystem is required by gatsby-plugin-image')
  process.exit(1)
}

When it happens

Trigger: Using gatsby-plugin-image's <StaticImage> component with a local file path without having gatsby-source-filesystem in the dependency tree. The require('gatsby-source-filesystem/create-file-node') throws MODULE_NOT_FOUND.

Common situations: Fresh project that added gatsby-plugin-image but forgot gatsby-source-filesystem. Monorepo where gatsby-source-filesystem is hoisted to a different workspace and not resolvable. Accidental removal of gatsby-source-filesystem from package.json.

Related errors

• Please install gatsby-plugin-sharp
• Failed to load image ${file} into sharp.
• Failed to write ${file} into ${outputPath}. (${err.message})
• Gatsby-plugin-sharp wasn't setup correctly in gatsby-config.
• starter ${starterPath} doesn't exist

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