{"record":{"id":"d49db7a440511118","repo":"gatsbyjs/gatsby","slug":"toformat-seems-to-be-empty-we-need-a-fileextensio","errorCode":null,"errorMessage":"toFormat seems to be empty, we need a fileExtension to set it.","messagePattern":"toFormat seems to be empty, we need a fileExtension to set it\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/gatsby-plugin-sharp/src/plugin-options.ts","lineNumber":186,"sourceCode":"  defaultArgs = {}\n): Partial<IGeneralArgs> & {\n  quality: number\n} & ITransformArgs => {\n  const options = defaults({}, args, { quality }, defaultArgs, generalArgs)\n  // @ts-ignore - parseInt as safeguard, expects string tho\n  options.quality = parseInt(options.quality, 10)\n  // @ts-ignore - parseInt as safeguard, expects string tho\n  options.pngCompressionLevel = parseInt(options.pngCompressionLevel, 10)\n  // @ts-ignore - parseInt as safeguard, expects string tho\n  options.pngCompressionSpeed = parseInt(options.pngCompressionSpeed, 10)\n  options.toFormat = options.toFormat.toLowerCase()\n  options.toFormatBase64 = options.toFormatBase64?.toLowerCase()\n  options.base64Width = options.base64Width || base64Width\n\n  // when toFormat is not set we set it based on fileExtension\n  if (options.toFormat === ``) {\n    if (!fileExtension) {\n      throw new Error(\n        `toFormat seems to be empty, we need a fileExtension to set it.`\n      )\n    }\n    options.toFormat = fileExtension.toLowerCase()\n\n    if (fileExtension === `jpeg`) {\n      options.toFormat = `jpg`\n    }\n  }\n\n  // only set width to 400 if neither width nor height is passed\n  if (options.width === undefined && options.height === undefined) {\n    options.width = 400\n  }\n  if (options.width !== undefined) {\n    // @ts-ignore - parseInt as safeguard, expects string tho\n    options.width = parseInt(options.width, 10)\n  }","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-plugin-sharp/src/plugin-options.ts#L168-L204","documentation":"In plugin-options.ts healOptions, the output format is taken from options.toFormat when set; otherwise it falls back to the source file's extension. If toFormat is empty AND no fileExtension can be determined (the source has no recognizable extension), the code cannot pick a target format and throws. Sharp requires an explicit output format (jpg, png, webp, avif) to encode.","triggerScenarios":"Processing an image whose path has no extension (e.g. a buffer or a tmp file named 'tmp-123') without setting toFormat; calling sharp APIs without format options on a file gatsby cannot introspect; a CMS delivering an image URL with a stripped extension.","commonSituations":"Remote images with no extension in the URL; files fetched into temp directories; misconfigured gatsby-plugin-sharp that loses the file extension during onCreateNode; custom transformers that rename files without extensions.","solutions":["Set toFormat explicitly in the sharp options or in gatsby-plugin-sharp pluginOptions, e.g. sharpOptions: { toFormat: 'webp' }.","Ensure the source file path ends with a recognized extension before processing.","If fetching remote images, derive and append the extension from Content-Type in onCreateNode."],"exampleFix":"// before\nsharp({ file: '/tmp/img-9281' }) // no extension, no toFormat\n\n// after\nsharp({ file: '/tmp/img-9281', toFormat: 'webp' })","handlingStrategy":"validation","validationCode":"function ensureToFormat(options, fileExtension) {\n  if (!options.toFormat) {\n    if (!fileExtension) {\n      throw new Error('toFormat is empty and no fileExtension available');\n    }\n    options.toFormat = fileExtension.toLowerCase();\n  }\n  return options;\n}","typeGuard":"function hasResolvableFormat(options, fileExtension) {\n  return Boolean(options.toFormat) || Boolean(fileExtension);\n}","tryCatchPattern":null,"preventionTips":["Always set toFormat when processing files without extensions (buffers, tmp files).","Preserve file extensions when downloading remote images (derive from Content-Type).","Validate sharp options before invoking the pipeline in custom transformers."],"tags":["gatsby-plugin-sharp","image-processing","validation","format"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}