{"record":{"id":"31086eabe5e9c330","repo":"gatsbyjs/gatsby","slug":"failed-to-load-image-file-into-sharp","errorCode":null,"errorMessage":"Failed to load image ${file} into sharp.","messagePattern":"Failed to load image (.+?) into sharp\\.","errorType":"exception","errorClass":"SharpError","httpStatus":null,"severity":"error","filePath":"packages/gatsby-plugin-sharp/src/process-file.ts","lineNumber":45,"sourceCode":"  args: ITransformArgs\n}\n\nexport const processFile = async (\n  file: string,\n  transforms: Array<ITransform>,\n  options = {} as ISharpPluginOptions\n): Promise<Array<ITransform>> => {\n  let pipeline\n  try {\n    const inputBuffer = await fs.readFile(file)\n    pipeline = sharp(inputBuffer, { failOn: options.failOn })\n\n    // Keep Metadata\n    if (!options.stripMetadata) {\n      pipeline = pipeline.withMetadata()\n    }\n  } catch (err) {\n    throw new SharpError(`Failed to load image ${file} into sharp.`, err)\n  }\n\n  return Promise.all(\n    transforms.map(async transform => {\n      try {\n        const { outputPath, args } = transform\n        log(`Start processing ${outputPath}`)\n        await fs.ensureDir(path.dirname(outputPath))\n\n        const transformArgs = healOptions(\n          { defaultQuality: options.defaultQuality as number },\n          args\n        )\n\n        let clonedPipeline = transforms.length > 1 ? pipeline.clone() : pipeline\n\n        if (transformArgs.trim) {\n          clonedPipeline = clonedPipeline.trim(transformArgs.trim)","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-plugin-sharp/src/process-file.ts#L27-L63","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the source file exists and is a valid image (file, identify image.png).","Ensure git-LFS or remote-file-fetch plugins resolved binary content before sharp runs.","Install/rebuild sharp for your platform (npm rebuild sharp) after node/libvips changes.","If the format is unsupported, convert the asset or rebuild libvips with the needed codec (e.g. libheif for HEIC).","Increase available memory for very large images or downscale the source."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const fs = require('fs');\nfunction assertImageReadable(file) {\n  if (!fs.existsSync(file)) throw new Error(`Image not found: ${file}`);\n  const stat = fs.statSync(file);\n  if (!stat.isFile() || stat.size === 0) throw new Error(`Image empty or not a file: ${file}`);\n}","typeGuard":"function isNonEmptyImageFile(file) {\n  try { const s = fs.statSync(file); return s.isFile() && s.size > 0; }\n  catch { return false; }\n}","tryCatchPattern":"try {\n  await processFile(file, transforms, options);\n} catch (err) {\n  if (err instanceof SharpError && /Failed to load image/.test(err.message)) {\n    reporter.warn(`Skipping unreadable image ${file}: ${err.message}`);\n    return; // skip this asset, continue build\n  }\n  throw err;\n}","preventionTips":["Validate remote image downloads completed and are non-empty before processing.","Resolve git-LFS pointers to real binaries before sharp runs.","Run `npm rebuild sharp` after node/platform changes."],"tags":["gatsby-plugin-sharp","image-processing","filesystem","corrupt-input"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}