gatsbyjs/gatsby · error · Error

url passed to createRemoteFileNode is either missing or not

Error message

url passed to createRemoteFileNode is either missing or not a proper web uri: ${url}

What it means

createRemoteFileNode rejects a URL that is falsy or fails the `isWebUri` check (validatable-weburi). The plugin must issue an HTTP GET, so it needs an absolute http/https URI. Anything else — a relative path, a malformed string, undefined, an FTP URL — is caught before any network call. Note the early processingCache short-circuit returns first, so a previously seen falsy key could mask this.

Source

Thrown at packages/gatsby-source-filesystem/src/create-remote-file-node.js:139

  }
  if (typeof getCache === `function`) {
    // use cache of this plugin and not cache of function caller
    cache = getCache(`gatsby-source-filesystem`)
  }
  if (typeof cache !== `object`) {
    throw new Error(
      `Neither "cache" or "getCache" was passed. getCache must be function that return Gatsby cache, "cache" must be the Gatsby cache, was ${typeof cache}`
    )
  }

  // Check if we already requested node for this remote file
  // and return stored promise if we did.
  if (processingCache[url]) {
    return processingCache[url]
  }

  if (!url || isWebUri(url) === undefined) {
    throw new Error(
      `url passed to createRemoteFileNode is either missing or not a proper web uri: ${url}`
    )
  }

  const fileDownloadPromise = processRemoteNode({
    url,
    cache,
    createNode,
    parentNodeId,
    createNodeId,
    auth,
    httpHeaders,
    ext,
    name,
  })

  processingCache[url] = fileDownloadPromise.then(node => node)

View on GitHub (pinned to 8b06340921)

Solutions

1. Validate the URL before calling: if (!url || isWebUri(url) === undefined) skip; then call createRemoteFileNode.
2. Prepend a base URL to relative paths: new URL(relative, baseUrl).toString().
3. Filter out falsy/empty url values in your sourceNodes loop before invoking the helper.
4. URL-encode any path segments that may contain spaces or unicode: encodeURI on the path portion only.

Example fix

// before
await createRemoteFileNode({ url: post.image, cache, createNode, createNodeId })

// after
if (post.image && isWebUri(post.image)) {
  await createRemoteFileNode({ url: post.image, cache, createNode, createNodeId })
}

const isWebUri = require('valid-url').isWebUri
if (!url || !isWebUri(url)) { throw new Error(`Skipping non-web URL: ${url}`) }

const isAbsoluteWebUrl = (u) => typeof u === 'string' && /^https?:\/\/.+\..+/i.test(u) && isWebUri(u) !== undefined

try { await createRemoteFileNode({ url, ...rest }) } catch (e) { if (/not a proper web uri/.test(e.message)) { reporter.warn(`Skipping invalid url: ${url}`); return } throw e }

When it happens

Trigger: Passing url: undefined or url: ''; passing a relative path like /images/foo.png; passing an FTP or file:// URL; passing a URL with spaces/unencoded characters that isWebUri rejects; passing a data URI.

Common situations: Reading a field from a remote source where the image/url field is sometimes empty; consuming an RSS feed or REST API that returns relative URLs; copy-paste that lost the protocol; environment where the upstream returns null for missing media.

Related errors

• Invalid plugin options for "gatsby-plugin-sitemap":
• 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

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