Skip to content

A base href tag sends your page links to the wrong domain

Inspect document.baseURI and resolved links when a staging base URL leaks into production, then verify navigation, assets, and fragment links after the repair.

By Crawlito · 5 min read

In short

  • A base href changes how relative URLs in a document resolve.
  • The written href and the browser-resolved destination can differ.
  • Verify the generated production base and representative links before replacing URLs in bulk.
On this page

If many links on a production page unexpectedly point to staging or the wrong folder, inspect its base href element. That element changes how relative URLs resolve, so apparently correct link text can lead elsewhere. Compare the written href with the browser's resolved destination, repair the base configuration, and test navigation and assets through the public page.

This is especially easy to miss when a site works at the root in development but is published under another path. The visible link label does not reveal the destination the browser calculated.

Inspect the base URL the browser uses

Open the affected page and inspect its head for a base element. In the browser console, read the document's effective base and a representative link:

javascript
document.baseURI;
const link = document.querySelector('a[href]');
[link?.getAttribute('href'), link?.href];

The first link expression reads the attribute as written; the second reads the resolved destination. Choose the actual failing link when reproducing the incident rather than relying on the first link on the page.

MDN's base element reference explains how the document base affects relative URLs and how multiple base elements are handled.

Record the public page URL, effective base, written href, and resolved URL together. These four values usually make the mismatch clear.

The internal-link guide covers destination checks, but this issue needs the document's resolution context as well.

Reproduce the failure with a small example

A hypothetical production page might contain:

html
<base href="https://staging.example.com/docs/">
<a href="setup">Setup guide</a>

The link text is ordinary, and the relative value may be correct for the intended site. The base sends it to the staging host.

A folder mismatch can be subtler. A base ending in a file-like path and one ending in a slash can produce different results for a relative destination. Use the actual URL resolution rather than guessing from the visual string.

Check root-relative links, path-relative links, and fragment links separately. They do not all behave like a plain absolute URL.

Do not repair the example by converting every link in the repository to an absolute URL before finding the source of the base. That can hide the configuration defect and create a large maintenance burden.

Trace the base to the build configuration

Find the template or framework setting that emits the base element. Compare development, preview, and production values.

A preview environment variable may have been baked into a static build. A deployed configuration change will not necessarily alter HTML already generated with the old value.

Inspect the public response source as well as the current browser DOM. If script changes the base after load, record when that happens and which component owns it.

The raw and rendered HTML guide helps separate build output from browser changes. Both can matter when a crawler or a user follows relative links.

Check whether multiple base elements are emitted by a layout and a nested component. Removing the wrong one can leave the effective base unchanged.

Keep the investigation scoped to the generated document. A server redirect is a separate mechanism and should not be used to compensate for every misresolved link.

Repair the intended resolution contract

If the site does not need a base element, review whether removing the unintended one is appropriate for its actual templates and assets. If it does need one, set the correct production value through the owning configuration.

Preserve intentional subpath hosting. A site under /docs/ may rely on that prefix for navigation and assets, so changing the base to the domain root can create another failure.

Test the build artifact before deploying. Inspect the emitted base and resolve representative links against it. Do not assume a correct source environment variable guarantees the final HTML uses it.

Update any absolute staging URLs separately where they genuinely exist. A base repair affects relative resolution; it does not rewrite an explicit https staging link.

The subpath publishing guide offers a related example of keeping generated paths aligned with the deployment location.

Verify navigation and assets together

After publication, open the public page in a fresh browser session. Follow a topic link, an image or stylesheet reference, a form action if relevant, and an in-page section link.

A page may look correct because some assets were cached even while new visitors request them from the wrong location. Check the Network panel and actual resolved URLs.

Use a small acceptance matrix:

ReferenceWhat to inspect
Path-relative linkIntended host and folder
Root-relative linkIntended host
Fragment linkCorrect document and section
Asset referenceCorrect public resource
Absolute linkExplicit destination remains appropriate

Fetch the destination content where practical. A resolved URL that returns the homepage instead of the guide is still wrong.

Keep the public source and browser-resolved result in the evidence. That proves both what was delivered and how the browser interpreted it.

A fragment link can resolve against the base URL's document rather than the page a reader expects. Test the real table of contents and copied section links.

Do not confuse this with hash-based application routing. A normal section anchor and a client-side route encoded after a hash are different designs.

Inspect canonical and alternate metadata if the site generates relative references there. Prefer the platform's supported, deliberate URL generation instead of relying on a stale base to repair incomplete values.

Check links in structured content imported from a CMS. The base may have concealed missing prefixes in old records. Removing it can reveal those assumptions, which should be fixed at their source.

For an audit report, identify whether the problem affects one template, one deployment environment, or the entire site. That scope determines how broad the verification sample should be.

Test the next release under its real location

Keep the production host and subpath in the release acceptance test. A local root deployment can pass while the actual nested deployment fails.

Include a preview build as a control. Preview links should stay within their intended environment without leaking that environment into production metadata.

If the site supports multiple public hosts or language prefixes, test each supported configuration rather than forcing one hard-coded base everywhere.

Document why the base exists and who owns its value. A future maintainer should not have to infer the contract from a mysterious tag.

After the repair, a useful completion statement names the actual result: production relative links resolve to the correct host and path, assets load there, and section links stay in the intended document.

Check both links authored directly in the page and URLs assembled by client code. A component may read document.baseURI while another uses an explicit configured origin, producing two different destinations from the same deployment. Capture the resolved URL for each failing action instead of fixing only the first visible anchor. Keep the regression example small enough that a future build change can reproduce the same resolution check.

Frequently asked questions

Can an href look correct in source but go to the wrong host?

Yes. Relative values are resolved using the document's effective base URL. Compare the written and resolved values.

No. An explicit absolute URL needs its own correction.

Only when it matches the site's intended URL design. It can change many references at once and should not conceal unrelated path errors.

Run the repaired public page through the free Crawlito check after testing its resolved destinations.

Filed under Rendering and content. Topics: html, internal-links, troubleshooting