gatsbyjs/gatsby · error · SharpError

Failed to load image ${file} into sharp.

Error message

Failed to load image ${file} into sharp.

What it means

process-file.ts loads the source image into a sharp pipeline by fs.readFile then sharp(buffer). Any failure - file missing, unreadable, truncated, zero-byte, unsupported/corrupt format, or sharp failing to construct - is wrapped in a SharpError with this message and the original error attached. SharpError is treated specially upstream (it surfaces as a build error rather than a generic failure).

Source

Thrown at packages/gatsby-plugin-sharp/src/process-file.ts:45

  args: ITransformArgs
}

export const processFile = async (
  file: string,
  transforms: Array<ITransform>,
  options = {} as ISharpPluginOptions
): Promise<Array<ITransform>> => {
  let pipeline
  try {
    const inputBuffer = await fs.readFile(file)
    pipeline = sharp(inputBuffer, { failOn: options.failOn })

    // Keep Metadata
    if (!options.stripMetadata) {
      pipeline = pipeline.withMetadata()
    }
  } catch (err) {
    throw new SharpError(`Failed to load image ${file} into sharp.`, err)
  }

  return Promise.all(
    transforms.map(async transform => {
      try {
        const { outputPath, args } = transform
        log(`Start processing ${outputPath}`)
        await fs.ensureDir(path.dirname(outputPath))

        const transformArgs = healOptions(
          { defaultQuality: options.defaultQuality as number },
          args
        )

        let clonedPipeline = transforms.length > 1 ? pipeline.clone() : pipeline

        if (transformArgs.trim) {
          clonedPipeline = clonedPipeline.trim(transformArgs.trim)

View on GitHub (pinned to 8b06340921)

Solutions

1. Verify the source file exists and is a valid image (file, identify image.png).
2. Ensure git-LFS or remote-file-fetch plugins resolved binary content before sharp runs.
3. Install/rebuild sharp for your platform (npm rebuild sharp) after node/libvips changes.
4. If the format is unsupported, convert the asset or rebuild libvips with the needed codec (e.g. libheif for HEIC).
5. Increase available memory for very large images or downscale the source.

const fs = require('fs');
function assertImageReadable(file) {
  if (!fs.existsSync(file)) throw new Error(`Image not found: ${file}`);
  const stat = fs.statSync(file);
  if (!stat.isFile() || stat.size === 0) throw new Error(`Image empty or not a file: ${file}`);
}

function isNonEmptyImageFile(file) {
  try { const s = fs.statSync(file); return s.isFile() && s.size > 0; }
  catch { return false; }
}

try {
  await processFile(file, transforms, options);
} catch (err) {
  if (err instanceof SharpError && /Failed to load image/.test(err.message)) {
    reporter.warn(`Skipping unreadable image ${file}: ${err.message}`);
    return; // skip this asset, continue build
  }
  throw err;
}

When it happens

Trigger: Processing a missing, deleted, or permission-denied file; processing a corrupt or zero-byte image; an image in a format sharp cannot decode on the installed libvips (e.g. some RAW, HEIC without libheif); a network image whose download was truncated; a file that is actually HTML/JSON disguised as an image.

Common situations: Broken remote image URLs; git-LFS pointers not resolved (the file is a text LFS pointer, not the image); npm/git not having fetched a binary asset; sharp/libvips version mismatch after upgrading gatsby-plugin-sharp; out-of-memory on very large images.

Related errors

• Failed to write ${file} into ${outputPath}. (${err.message})
• Could not find matching operation for ${requestedPathOnDisk}
• ${fixedDimension} has to be a positive int larger than zero
• All ints in srcSetBreakpoints should be positive ints larger
• toFormat seems to be empty, we need a fileExtension to set i

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