Why does metadataBase create the wrong canonical URL?
Relative metadata URLs resolve against metadataBase. A localhost, branch, or deployment hostname there can leak into canonical and social tags across the entire site.
Written for next.js teams using relative alternates and Open Graph URLs across local, preview, and production deployments.
Key facts
- Next.js uses metadataBase to resolve URL-based metadata fields that are supplied as relative paths.
- A wrong base can affect canonical, Open Graph, and other metadata across many routes.
- Production canonical identity should not change with the host that served a preview build.
A useful rule: make each important claim understandable and verifiable without requiring the reader to reconstruct your meaning from the rest of the page.
How does metadataBase affect URLs?
`metadataBase` provides the base URL used when URL-valued metadata is declared relatively. A canonical such as `/blog/example` and an Open Graph image such as `/og/example.png` become absolute using that base. This is convenient because route records can remain host-independent, but it makes the base a high-impact configuration. If it points to localhost or a platform preview URL, every inherited page may advertise the wrong identity. Inspect final tags rather than assuming the deployment hostname will be replaced automatically.
- List every metadata field that resolves from a relative URL.
- Fetch final output on each environment.
- Treat metadataBase as public identity configuration.
Where should the production origin come from?
Use one explicitly configured canonical site URL that includes the preferred protocol and hostname. Validate it during build and fail production builds when it is missing, malformed, localhost, or a temporary deployment domain. Do not derive canonical identity from an untrusted request Host header, because alternate domains or preview hosts can then become self-canonical. Preview builds may still use production canonical URLs if they are publicly accessible; better yet, protect or noindex previews according to the hosting model.
- Define one canonical origin environment variable.
- Validate protocol and hostname.
- Keep preview accessibility policy separate from canonical generation.
Why can only some routes be wrong?
Nested layouts merge metadata, and pages can override individual fields. One route may supply an absolute canonical while another inherits a relative value. Dynamic `generateMetadata` may also construct URLs manually and bypass the shared base. Search the codebase for `alternates`, `openGraph`, `twitter`, and URL constructors, then create a table of ownership by route. Consolidate public URL formation in one helper and avoid mixing trailing-slash policies. A few correct pages do not prove the global configuration is safe.
- Audit layout inheritance and page overrides.
- Replace ad hoc URL concatenation with one helper.
- Normalize the chosen trailing-slash policy.
Sources: 1
How does a wrong base affect search?
Canonical tags become one signal among several, so search engines may ignore the mistake or may consolidate toward the wrong host when other signals agree. Social crawlers can request images from an inaccessible preview deployment and produce blank cards. Analytics and link sharing can fragment across origins. Correct the base, sitemap URLs, redirects, internal links, and structured-data identifiers together so document identity converges. Do not rely on canonical alone to repair an environment leaked into public navigation.
- Align canonical, sitemap, redirects, links, and JSON-LD IDs.
- Test social image accessibility anonymously.
- Monitor selected canonicals after deployment.
What automated checks prevent recurrence?
After a production build, request representative routes and extract every canonical, Open Graph URL, image URL, structured-data ID, and sitemap location. Assert the expected origin and reject localhost, private IPs, and known preview suffixes. Run the same parser on an article and tool whose metadata is dynamic. Add a test for Unicode, query strings, and nested paths so URL composition cannot silently truncate or duplicate segments. These checks are inexpensive and catch a configuration error capable of affecting the entire site. Save the extracted values as reviewable deployment evidence.
- Scan all generated public URLs for forbidden hosts.
- Cover static and dynamic routes.
- Test encoding and nested path composition.
Put it to work
Find the highest-impact fix on your site.
Find canonical, social, sitemap, and JSON-LD URLs that resolve to a preview or local hostname.
Check canonical originsSources
- 1.Next.js documentation: generateMetadataChecked 2026-07-26
- 2.Google Search Central: Specify canonical URLsChecked 2026-07-26