gatsbyjs/gatsby · error · Error

RemoteFileNode does not have a mimeType. The field is requir

Error message

RemoteFileNode does not have a mimeType. The field is required.

What it means

Thrown by isImage() in polyfill-remote-file/types when a RemoteFileNode passed to an image resolver has no mimeType field. The function needs mimeType to determine if the file is an image (starts with 'image/' and is not SVG). A missing mimeType means the source plugin did not populate file metadata.

Source

Thrown at packages/gatsby-plugin-utils/src/polyfill-remote-file/types.ts:89

export type WidthOrHeight =
  | { width: number; height: number }
  | { width: number; height?: never }
  | { width?: never; height: number }

export type CalculateImageSizesArgs = {
  fit: ImageFit
  layout: ImageLayout
  outputPixelDensities: Array<number>
  breakpoints?: Array<number>
  aspectRatio?: number
} & WidthOrHeight

export function isImage(node: {
  mimeType: IRemoteFileNode["mimeType"]
}): node is IRemoteImageNode {
  if (!node.mimeType) {
    throw new Error(
      `RemoteFileNode does not have a mimeType. The field is required.`
    )
  }

  return node.mimeType.startsWith(`image/`) && node.mimeType !== `image/svg+xml`
}

export type ImageCdnTransformArgs = WidthOrHeight & {
  format: string
  cropFocus?: ImageCropFocus | Array<ImageCropFocus>
  quality: number
}

// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
type CdnSourceImage = {
  url: string
  mimeType: string
  filename: string

View on GitHub (pinned to 8b06340921)

Solutions

1. Ensure the source plugin populates mimeType when creating remote file nodes (fetch content-type from the remote response).
2. If using gatsby-source-filesystem or a CDN source, verify the remote server returns a valid Content-Type header.
3. Manually set mimeType on the node before it reaches the image resolver if the source cannot provide it.
4. Filter nodes to only pass those with a mimeType to image resolvers.

Example fix

// before
createNode({ ...fileData, internal: { type: 'File' } })
// after
createNode({ ...fileData, mimeType: response.headers['content-type'], internal: { type: 'File' } })

// Check mimeType before passing node to image resolvers
if (!node.mimeType) {
  throw new Error(`File node ${node.id} is missing mimeType — cannot use as image`)
}

function hasMimeType(node: { mimeType?: string }): node is { mimeType: string } {
  return typeof node.mimeType === 'string' && node.mimeType.length > 0
}

// usage: if (hasMimeType(node)) { isImage(node) }

try {
  if (isImage(node)) { /* process image */ }
} catch (e) {
  if (e.message.includes('mimeType')) {
    // skip this node or fetch its mimeType first
  } else throw e
}

When it happens

Trigger: node.mimeType is undefined/null/falsy when isImage(node) is called; the guard throws before the image check because mimeType is a prerequisite.

Common situations: A source plugin created a RemoteFileNode without fetching/storing mimeType, the content CDN did not return a content-type header, or a custom file creation bypassed the normal metadata enrichment.

Related errors

• The "layout" argument is required for "${source.url}"
• Either the "width" or "height" argument is required f
• The provided width of "${width}" is incorrect. Dimensions sh
• The provided height of "${height}" is incorrect. Dimensions
• Unknown format "${args.format}" was given to resize ${source

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