gatsbyjs/gatsby · error

error converting image

Error message

error converting image

What it means

In gatsby-plugin-sharp's createJob (index.js:142-144), after actions is confirmed present, it calls actions.createJobV2(job) to queue the image transformation. If the job promise rejects (e.g. sharp fails to process the image, corrupt input, unsupported format, out of memory), the .catch handler calls reporter.panic('error converting image', err). The second argument err is the original sharp error.

Source

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

  }
}

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
}

function lazyJobsEnabled() {
  return (
    process.env.gatsby_executing_command === `develop` &&
    (!isCI() || process.env.GATSBY_ENABLE_LAZY_IMAGES_IN_CI) &&
    !(
      process.env.ENABLE_GATSBY_EXTERNAL_JOBS === `true` ||
      process.env.ENABLE_GATSBY_EXTERNAL_JOBS === `1`
    )
  )
}

function queueImageResizing({ file, args = {}, reporter }) {
  const fullOptions = healOptions(getPluginOptions(), args, file.extension)

View on GitHub (pinned to 8b06340921)

Solutions

1. Check the err object in the panic output for the specific sharp error (e.g. 'Input buffer contains unsupported image format')
2. Verify the source image is a valid, non-corrupt raster image (open it in an image viewer)
3. If sharp native binding fails: npm rebuild sharp or install system libvips
4. For memory issues, reduce image dimensions before processing or increase Node memory: NODE_OPTIONS=--max-old-space-size=4096
5. For SVGs, exclude them from sharp processing or use a different plugin

Example fix

// before: corrupt or unsupported image in the pipeline
// Identify from the err in the panic output, then:

// Fix: replace/re-export the corrupt image
// Or exclude it from processing:
// In GraphQL query, add a conditional to skip broken images

// For sharp native issues:
// npm rebuild sharp
// or
// npm install sharp --build-from-source

// Pre-build: validate all source images are processable
const fs = require('fs')
const supportedFormats = ['.png', '.jpg', '.jpeg', '.webp', '.tiff', '.gif', '.avif']

function validateImages(dir) {
  const files = fs.readdirSync(dir, { recursive: true })
  for (const file of files) {
    const ext = path.extname(file).toLowerCase()
    if (ext && !supportedFormats.includes(ext)) {
      console.warn(`Potentially unsupported image format: ${file}`)
    }
  }
}

// Wrap sharp image processing with retry logic (in your own code
// that invokes sharp-based APIs):
async function processImageWithRetry(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn()
    } catch (err) {
      if (i === retries - 1) throw err
      await new Promise(r => setTimeout(r, 1000 * (i + 1)))
    }
  }
}

When it happens

Trigger: Processing a corrupt or truncated image file. Unsupported image format (e.g. SVG passed to sharp resize). Insufficient memory for large image operations. Sharp native binding failure (missing libvips). Permission denied reading the source file.

Common situations: Large RAW/TIFF images that exhaust memory. Corrupted JPEG/PNG files from a CMS. Sharp version mismatch with system libvips. SVG files accidentally processed through raster pipeline. Container/CI environments without proper sharp native dependencies.

Related errors

• Processing ${file} failed
• Please install gatsby-plugin-sharp
• Gatsby-plugin-sharp wasn't setup correctly in gatsby-config.
• Image downloading failed for ${originalImg}, please check if
• Specified dimensions for images must be positive numbers (>

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