vercel/next.js · error · Error

metadataBase is not a valid URL

Error message

metadataBase is not a valid URL: ${metadataBase}

What it means

Metadata validation in normalizeMetadataBase: the user-supplied metadataBase value is a string that the URL constructor cannot parse, so relative metadata URLs (canonical, openGraph, twitter images) cannot be resolved against it. The offending input is the metadataBase field of the route's metadata export.

Solutions

1. Set metadataBase to a valid absolute URL (e.g. new URL('https://example.com')).

When it happens

Trigger: metadata.metadataBase is set to a value that is not a valid URL.

Common situations: A typo or missing protocol in metadataBase in layout metadata or next.config.

AI-assisted analysis of vercel/next.js@996f957c06 (2026-08-19). Data as JSON: /api/errors/32ad0266508e9da0. Report an issue: GitHub.

Appendix: source

Thrown at packages/next/src/lib/metadata/metadata-resolution-primitives.ts:155

    return input.map((item) =>
      convertUrlsToStrings(item)
    ) as WithStringifiedURLs<T>
  } else if (input && typeof input === 'object') {
    const result: Record<string, unknown> = {}
    for (const [key, value] of Object.entries(input)) {
      result[key] = convertUrlsToStrings(value)
    }
    return result as WithStringifiedURLs<T>
  }
  return input as WithStringifiedURLs<T>
}

function normalizeMetadataBase(metadataBase: string | URL | null): URL | null {
  if (typeof metadataBase === 'string') {
    try {
      metadataBase = new URL(metadataBase)
    } catch {
      throw new Error(`metadataBase is not a valid URL: ${metadataBase}`)
    }
  }
  return metadataBase
}

async function mergeStaticMetadata(
  metadataBase: MetadataBaseURL,
  source: Metadata | null,
  target: ResolvedMetadata,
  staticFilesMetadata: StaticMetadata,
  metadataContext: MetadataContext,
  titleTemplates: TitleTemplates,
  leafSegmentStaticIcons: StaticIcons,
  pathname: Promise<string>
): Promise<ResolvedMetadata> {
  if (!staticFilesMetadata) return target
  const { icon, apple, openGraph, twitter, manifest } = staticFilesMetadata

View on GitHub (pinned to 996f957c06)