{"record":{"id":"9dabea10a05de985","repo":"gatsbyjs/gatsby","slug":"processing-file-failed","errorCode":null,"errorMessage":"Processing ${file} failed","messagePattern":"Processing (.+?) failed","errorType":"exception","errorClass":"SharpError","httpStatus":null,"severity":"error","filePath":"packages/gatsby-plugin-sharp/src/process-file.ts","lineNumber":146,"sourceCode":"            clonedPipeline\n          )\n        }\n\n        try {\n          const buffer = await clonedPipeline.toBuffer()\n          await fs.writeFile(outputPath, buffer)\n        } catch (err) {\n          throw new Error(\n            `Failed to write ${file} into ${outputPath}. (${err.message})`\n          )\n        }\n      } catch (err) {\n        if (err instanceof SharpError) {\n          // rethrow\n          throw err\n        }\n\n        throw new SharpError(`Processing ${file} failed`, err)\n      }\n\n      return transform\n    })\n  )\n}\n\nexport const createArgsDigest = (args: unknown): string => {\n  const argsDigest = createContentDigest(args)\n\n  return argsDigest.slice(-5)\n}\n","sourceCodeStart":128,"sourceCodeEnd":159,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-plugin-sharp/src/process-file.ts#L128-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped err (the underlying sharp message) to find the failing operation.","Isolate the problematic image and test with `npx sharp-cli` outside Gatsby to reproduce.","Update or pin sharp/libvips to a version compatible with your gatsby-plugin-sharp.","Adjust the transform args (e.g. remove duotone/trim, change fit, lower trimThreshold).","Re-save or normalize the source image (strip problematic ICC, flatten alpha) if it is a malformed asset."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"async function trySharpPipeline(file, args) {\n  // probe with a tiny transform to catch unsupported ops early\n  const tmp = await sharp(file).resize(1).toBuffer({ resolveWithObject: true });\n  return tmp;\n}","typeGuard":"async function canProcess(file) {\n  try { await sharp(file).metadata(); return true; } catch { return false; }\n}","tryCatchPattern":"try {\n  await processFile(file, transforms, options);\n} catch (err) {\n  if (err instanceof SharpError && /Processing .* failed/.test(err.message)) {\n    reporter.warn(`Skipping problematic image ${file}: ${err.message}`);\n    return;\n  }\n  throw err;\n}","preventionTips":["Pin sharp/libvips versions compatible with your gatsby-plugin-sharp.","Quarantine assets that fail once and alert rather than retrying in a loop.","Validate transform args (duotone colors, fit, trim) against sharp's current API."],"tags":["gatsby-plugin-sharp","image-processing","transform","sharp"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}