Gatsby-plugin-sharp wasn't setup correctly in gatsby-config.

Error message

Gatsby-plugin-sharp wasn't setup correctly in gatsby-config.js. Make sure you add it to the plugins array.

What it means

In gatsby-plugin-sharp's createJob function (index.js:128-133), a module-level 'actions' variable is expected to be populated (set during the plugin's setup lifecycle). If actions is still falsy/undefined when createJob is called, it means the plugin's setup hook did not run — typically because gatsby-plugin-sharp is not properly registered in the gatsby-config.js plugins array. reporter.panic fires with this message.

Source

Thrown at packages/gatsby-plugin-sharp/src/index.js:130

  const prefixedSrc =
    (pathPrefix ? pathPrefix : ``) +
    `/static/${digestDirPrefix}` +
    encodedImgSrc

  return {
    src: prefixedSrc,
    outputDir: outputDir,
    relativePath: outputFilePath,
    width,
    height,
    aspectRatio,
    options: removeDefaultValues(args, getPluginOptions()),
  }
}

function createJob(job, { reporter }) {
  if (!actions) {
    reporter.panic(
      `Gatsby-plugin-sharp wasn't setup correctly in gatsby-config.js. Make sure you add it to the plugins array.`
    )
  }

  // Jobs can be duplicates and usually are long running tasks.
  // Because of that we shouldn't use async/await and instead opt to use
  // .then() /.catch() handlers, because this allows V8 to release
  // duplicate jobs from memory quickly (as job is not referenced
  // in resolve / reject handlers). If we would use async/await
  // entire closure would keep duplicate job in memory until
  // initial job finish.
  const promise = actions.createJobV2(job).catch(err => {
    reporter.panic(`error converting image`, err)
  })

  return promise
}

View on GitHub (pinned to 8b06340921)

Solutions

Add gatsby-plugin-sharp to the plugins array in gatsby-config.js
Ensure it appears before plugins that depend on it (e.g. gatsby-transformer-sharp)
Run npm install gatsby-plugin-sharp if not yet installed
Restart the Gatsby development server after config changes

Example fix

// before (gatsby-config.js)
plugins: [
  `gatsby-transformer-sharp`,
  // gatsby-plugin-sharp missing
],

// after
plugins: [
  `gatsby-plugin-sharp`,
  `gatsby-transformer-sharp`,
],

Defensive patterns

Strategy: validation

Validate before calling

// Validate gatsby-config.js has gatsby-plugin-sharp before building
const config = require('./gatsby-config')
const hasSharp = config.plugins.some(p =>
  typeof p === 'string' ? p === 'gatsby-plugin-sharp' : p.resolve === 'gatsby-plugin-sharp'
)
if (!hasSharp) {
  throw new Error('gatsby-plugin-sharp must be in the plugins array')
}

Prevention

Always list gatsby-plugin-sharp in gatsby-config.js plugins array
Place gatsby-plugin-sharp before gatsby-transformer-sharp in the plugins order
Run a config validation script before builds to catch missing plugins

When it happens

Trigger: Another plugin or user code calls into gatsby-plugin-sharp's queueImageResizing or generateImageData pipeline, but gatsby-plugin-sharp was never initialized because it is missing from gatsby-config.js plugins. The actions variable was never assigned via the plugin's onPreInit or createResolvers lifecycle.

Common situations: Using gatsby-transformer-sharp (which depends on gatsby-plugin-sharp) without listing gatsby-plugin-sharp in plugins. Plugin listed as a string dependency instead of in gatsby-config. Plugin installed but not added to the config after a refactor.

Related errors

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