gatsbyjs/gatsby · error · SharpError

Processing ${file} failed

Error message

Processing ${file} failed

What it means

process-file.ts wraps each transform in a try/catch. Any error that is NOT already a SharpError (i.e. not the load failure from error 54 or the explicit write failure from error 55) is wrapped in a generic SharpError 'Processing <file> failed' with the original error attached. This is the catch-all for unexpected sharp pipeline failures: resize/composite/rotate errors, duotone errors, trim/blur failures, and sharp internal exceptions.

Source

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

            clonedPipeline
          )
        }

        try {
          const buffer = await clonedPipeline.toBuffer()
          await fs.writeFile(outputPath, buffer)
        } catch (err) {
          throw new Error(
            `Failed to write ${file} into ${outputPath}. (${err.message})`
          )
        }
      } catch (err) {
        if (err instanceof SharpError) {
          // rethrow
          throw err
        }

        throw new SharpError(`Processing ${file} failed`, err)
      }

      return transform
    })
  )
}

export const createArgsDigest = (args: unknown): string => {
  const argsDigest = createContentDigest(args)

  return argsDigest.slice(-5)
}

View on GitHub (pinned to 8b06340921)

Solutions

1. Inspect the wrapped err (the underlying sharp message) to find the failing operation.
2. Isolate the problematic image and test with `npx sharp-cli` outside Gatsby to reproduce.
3. Update or pin sharp/libvips to a version compatible with your gatsby-plugin-sharp.
4. Adjust the transform args (e.g. remove duotone/trim, change fit, lower trimThreshold).
5. Re-save or normalize the source image (strip problematic ICC, flatten alpha) if it is a malformed asset.

async function trySharpPipeline(file, args) {
  // probe with a tiny transform to catch unsupported ops early
  const tmp = await sharp(file).resize(1).toBuffer({ resolveWithObject: true });
  return tmp;
}

async function canProcess(file) {
  try { await sharp(file).metadata(); return true; } catch { return false; }
}

try {
  await processFile(file, transforms, options);
} catch (err) {
  if (err instanceof SharpError && /Processing .* failed/.test(err.message)) {
    reporter.warn(`Skipping problematic image ${file}: ${err.message}`);
    return;
  }
  throw err;
}

When it happens

Trigger: An image-specific sharp failure during transform: invalid resize parameters sharp rejects at runtime, unsupported operation chaining, duotone with malformed colors, rotate without EXIF, crop gravity on an incompatible image, or a sharp bug. Distinguished from 54/55 by happening after load and during/after the transform pipeline.

Common situations: A specific image triggers a sharp edge case (e.g. extremely large dimensions, 1px image, animated gif treated as static, ICC profile sharp cannot parse); upgrading sharp/libvips and an op was removed; passing options sharp no longer accepts.

Related errors

• 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
• ${prop} has to be a positive int larger than zero (> 0), now

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