gatsbyjs/gatsby · error

${REPORTER_PREFIX} Error resolving Site URL

Error message

${REPORTER_PREFIX} Error resolving Site URL

What it means

In gatsby-plugin-sitemap's onPostBuild (gatsby-node.js:25-27), the plugin calls resolveSiteUrl(queryRecords) wrapped in Promise.resolve (to handle both sync and async implementations). If resolveSiteUrl throws synchronously or its returned promise rejects, the .catch handler calls reporter.panic with the REPORTER_PREFIX and the error. resolveSiteUrl is a user-provided (or default) function that extracts the site URL from the GraphQL query result.

Source

Thrown at packages/gatsby-plugin-sitemap/src/gatsby-node.js:26

exports.onPostBuild = async (
  { graphql, reporter, basePath, pathPrefix },
  {
    output,
    entryLimit,
    query,
    excludes,
    resolveSiteUrl,
    resolvePagePath,
    resolvePages,
    filterPages,
    serialize,
  }
) => {
  const { data: queryRecords, errors } = await graphql(query)

  // resolvePages and resolveSiteUrl are allowed to be sync or async. The Promise.resolve handles each possibility
  const siteUrl = await Promise.resolve(resolveSiteUrl(queryRecords)).catch(
    err => reporter.panic(`${REPORTER_PREFIX} Error resolving Site URL`, err)
  )

  if (errors) {
    reporter.panic(
      `Error executing the GraphQL query inside gatsby-plugin-sitemap:\n`,
      errors
    )
  }

  const allPages = await Promise.resolve(resolvePages(queryRecords)).catch(
    err => reporter.panic(`${REPORTER_PREFIX} Error resolving Pages`, err)
  )

  if (!Array.isArray(allPages)) {
    reporter.panic(
      `${REPORTER_PREFIX} The \`resolvePages\` function did not return an array.`
    )
  }

View on GitHub (pinned to 8b06340921)

Solutions

  1. Ensure siteMetadata.siteUrl is set in gatsby-config.js: siteMetadata: { siteUrl: 'https://example.com' }
  2. If using a custom resolveSiteUrl, add null checks and error handling inside it
  3. Verify the default GraphQL query returns the expected { site: { siteMetadata: { siteUrl } } } shape
  4. Check the err object in the panic output for the specific failure

Example fix

// before (gatsby-config.js) — missing siteUrl
siteMetadata: {
  title: `My Site`,
  // siteUrl missing
},

// after
siteMetadata: {
  title: `My Site`,
  siteUrl: `https://www.example.com`,
},
Defensive patterns

Strategy: validation

Validate before calling

// Pre-build: verify siteUrl is set and resolveSiteUrl won't fail
const config = require('./gatsby-config')
const siteUrl = config.siteMetadata?.siteUrl
if (!siteUrl) {
  throw new Error('siteMetadata.siteUrl is required for gatsby-plugin-sitemap')
}
try {
  new URL(siteUrl)
} catch {
  throw new Error(`siteUrl is not a valid URL: ${siteUrl}`)
}

Type guard

function isValidUrl(url: string): boolean {
  try {
    new URL(url)
    return true
  } catch {
    return false
  }
}

// Validate before build
const siteUrl = config.siteMetadata?.siteUrl
if (!siteUrl || !isValidUrl(siteUrl)) {
  throw new Error('siteMetadata.siteUrl must be a valid URL')
}

Try / catch

// If using a custom resolveSiteUrl, wrap it defensively:
resolveSiteUrl: (data) => {
  const url = data?.site?.siteMetadata?.siteUrl
  if (!url) {
    throw new Error('siteUrl not found in query data — check siteMetadata config')
  }
  return url
}

Prevention

When it happens

Trigger: A custom resolveSiteUrl function throws (e.g. accessing undefined property like data.site.siteMetadata.url when the query didn't return site metadata). The default resolveSiteUrl tries to read siteUrl from a query result that has an unexpected shape. The GraphQL query is misconfigured so queryRecords is null/undefined.

Common situations: Missing siteUrl in gatsby-config.js (siteMetadata). Custom resolveSiteUrl that doesn't handle edge cases. GraphQL query changed but resolveSiteUrl not updated. siteUrl not set in gatsby-config siteMetadata.

Related errors

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