gatsbyjs/gatsby · error

You can't use childImageSharp together with ${parent.name}.$

Error message

You can't use childImageSharp together with ${parent.name}.${parent.extension} — use publicURL instead. The childImageSharp portion of the query in this file will return null:\n${context.componentPath}

What it means

Error "You can't use childImageSharp together with ${parent.name}.${parent.extension} — use publicURL instead. The childImageSharp portion of the query in this file will return null:\n${context.componentPath}" thrown in gatsbyjs/gatsby.

Source

Thrown at packages/gatsby-transformer-sharp/src/create-resolvers.js:15

const { supportedExtensions } = require(`./supported-extensions`)

module.exports = ({ createResolvers, reporter }, pluginOptions = {}) => {
  const { checkSupportedExtensions = true } = pluginOptions

  const resolvers = {
    File: {
      childImageSharp: {
        resolve: (parent, args, context, info) => {
          // TODO: In future when components from GraphQL are possible make sure that we can support both supported & unsupported image formats
          if (
            !supportedExtensions[parent.extension] &&
            checkSupportedExtensions
          ) {
            reporter.warn(
              `You can't use childImageSharp together with ${parent.name}.${parent.extension} — use publicURL instead. The childImageSharp portion of the query in this file will return null:\n${context.componentPath}`
            )
          }
          return info.originalResolver(parent, args, context, info)
        },
      },
    },
  }

  createResolvers(resolvers)
}

View on GitHub (pinned to e85d62f177)

Solutions

1. Query publicURL instead of childImageSharp for non-image files (PDFs, SVGs, videos, etc.)
2. Remove the childImageSharp fragment from the query for that file type, or conditionally query it only for supported extensions
3. If you expect the file to be an image, check its actual extension — it may be misnamed or unsupported by sharp
4. Set checkSupportedExtensions: false in gatsby-transformer-sharp options only if you accept null results

When it happens

Trigger: Thrown at packages/gatsby-transformer-sharp/src/create-resolvers.js:15 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/9b4fe0ed3744acd0. Report an issue: GitHub.