A broken anchor link is a link with a #fragment, like /pricing#enterprise, where the target page has no element with id="enterprise". The page itself loads fine, so nothing reports an error: a visitor arriving from another page lands at the top, and a jump link on the same page does nothing at all. Anchors usually break when someone renames a heading and its generated id changes, when a page builder rebuilds a section, or when the id only appears after JavaScript runs. To find them, compare each fragment with the ids in the target page's HTML: by hand in DevTools for one link, or with a crawler that checks anchors for the whole site.
How a browser resolves #fragment
The HTML standard spells out the lookup (WHATWG HTML). The browser looks for an element whose id equals the fragment exactly, then for an <a name="..."> with that name, then tries both again with the fragment percent-decoded. An empty fragment or #top goes to the top of the page even with no matching element. If nothing matches, the browser doesn't scroll anywhere.
| Link | What the target page has | Result |
|---|---|---|
#pricing |
<h2 id="pricing"> |
Works |
#Pricing |
<h2 id="pricing"> |
Broken: the match is case-sensitive |
#faq |
<a name="faq"> |
Works (old-style named anchor) |
#caf%C3%A9 |
<h2 id="café"> |
Works: the fragment is decoded |
#top |
No element with that id | Goes to the top anyway |
#plans |
Two elements with id="plans" |
Goes to the first one |
#step-2 |
An id added by JavaScript after the page loads | Usually stays at the top |
The last row comes from timing. The browser keeps trying to find the fragment's target while the HTML is still being parsed and stops once parsing ends (WHATWG HTML), so an id that a script inserts later is too late, unless the site's own script handles the scroll.
Why anchor links stop working
- A heading was renamed and its id was generated from the text. Many CMSs, documentation tools and Markdown renderers build the id from the heading, so changing "Pricing plans" to "Plans and pricing" silently turns
#pricing-plansinto#plans-and-pricing. Docusaurus, which generates ids this way by default, offers explicit ids so you can "change or translate the text without updating the existing ID to avoid breaking links" (Docusaurus docs). - A page builder section was deleted and recreated, or copied from another page, and lost the id the links were using.
- The case or spelling differs:
#Pricingagainstid="pricing", or a space typed into an anchor field that the builder turned into a hyphen. - The section moved to another page. It now lives on
/plans, and every/pricing#enterpriselink still points at the old page. - The content is rendered by JavaScript: tabs, accordions and single-page apps that create sections after load.
- A table-of-contents plugin was replaced. Switching plugins can change the id scheme for every heading at once.
Check one anchor in DevTools
Open the target page, open the Console (F12, or Cmd+Option+I on a Mac) and run:
document.getElementById('pricing')
An element means the anchor exists. null means it doesn't. Then check for an old-style named anchor with document.getElementsByName('pricing').length, and look for near misses (case, renamed headings) with:
[...document.querySelectorAll('[id]')].map(el => el.id).filter(id => /pric/i.test(id))
To find out whether the id is in the HTML the server sends or only appears after scripts run, open view-source: for the page and search for id="pricing". If it's in the Elements panel but not in the source, it's added by JavaScript.
Find every broken anchor on a site
Checking anchors at scale means fetching every page that is the target of a #fragment link, collecting its ids and named anchors, and comparing. A plain status-code checker can't do it, because the page returns 200 either way. Options:
- lychee checks fragments with
--include-fragments(anchor-only,text-onlyorfull) (lychee README). The CI guide shows it failing a pull request on a missing anchor. - Docusaurus checks heading anchors at build time with
onBrokenAnchors. In version 3 the default only prints a warning (Docusaurus config), so set it to'throw'if you want the build to fail. - Linkbruno reports "the #section a link points to is missing", with every page that carries the link and where on the page it sits. It reads HTML as served and doesn't run JavaScript, so ids added by scripts show up as missing; check those in the browser before changing anything. The free scan runs on up to 25 pages without signing up, and the page link checker does one page. Both check links to a section of another page, not
#links within the same page.
Whatever you use, skip fragments that aren't anchors: a bare # used as a click handler, #!/route in older single-page apps that use the fragment for routing, #top, and text fragments (below). Fix links in navigation, footers and tables of contents first, because they repeat on every page. For other kinds of dead links, see how to find broken links.
Fixing a broken anchor
The right fix depends on who controls the link:
Your own links: change the fragment to the current id. If the heading's id was generated from its text, give it an explicit id at the same time so the next rename doesn't break it again.
Links from other sites, old emails or bookmarks: keep the old name working on the target page. An element has only one id, so put the old one on an empty element just above the section, such as
<span id="pricing-plans"></span>, or use an old-style<a name="pricing-plans"></a>.A whole page moved: a 301 is enough. Browsers never send the fragment to the server, and when a redirect's
Locationhas no fragment of its own, the browser carries the original one over (RFC 9110). So/pricing#enterpriseredirected to/planslands on/plans#enterprise.One section moved to another page: the server can't help, because it never sees
#enterprise. Update your own links, and for outside links add a line of script to the old page:if (location.hash === '#enterprise') location.replace('/plans#enterprise');The section is gone: link to the page without the fragment, or to wherever that information lives now. For whole pages that are gone, see fixing broken links.
Builder notes
WordPress block editor
Select the block, open Block settings, click Advanced and type the name into the HTML anchor field. WordPress's rules: unique on the page, case-sensitive, no spaces, must start with a letter, and only hyphens, underscores, colons and periods as symbols. Link to it as #name, or example.com/page#name from another page (WordPress docs). For broken links elsewhere in WordPress, see finding broken links in WordPress.
Elementor
Select the target element, open the Advanced tab and fill in CSS ID. Elementor allows only letters, numbers, hyphens and underscores, and says not to put a # in the field. Link to #name on the same page or www.mysite.com/myarticle#name from elsewhere (Elementor help).
Squarespace 7.1
In the page editor, choose Edit Section and enter a slug under Anchor Link; spaces become dashes automatically. Each slug can be used once per page. Anchors work on auto layout, block, course, gallery and video sections, but not on blog, events, portfolio or store sections; Squarespace's workaround is a blank section directly above. If you change the page slug, the anchor slug or your primary domain, update the links, because "Anchor links won't work correctly with outdated URLs." Version 7.0 has no section anchors and uses code blocks instead (Squarespace help). More in the Squarespace guide.
Webflow
Select the element, open the Element settings panel and type a unique ID with no spaces. On the same page, link with Link settings > Page section and pick it from the Section dropdown. For a section on another page, Webflow has you choose the URL link type and type the address with #id, such as site.com/page#section-id, or site.com/#section-id for the home page (Webflow help). Those are typed text, so renaming the ID later leaves them pointing at the old name. More in the Webflow guide.
The link works but lands in the wrong place
When the anchor exists but the heading ends up hidden under a sticky header, give the browser an offset. Fragment navigation uses the target's scroll margin even when scroll snapping is off (CSS Scroll Snap spec), and scroll-margin-top has been available across browsers since April 2021 (MDN):
/* Offset every jump target by the header height */
h2[id], h3[id], section[id] {
scroll-margin-top: 5rem;
}
/* Or set it once on the page's scroll container */
html {
scroll-padding-top: 5rem;
}
If the jump lands too high or too low by a varying amount, images above the target may be loading lazily and changing the page height after the scroll. Webflow's help describes this and suggests loading those images eagerly or placing them in fixed-height elements (Webflow help).
Text fragments aren't anchors
Links ending in #:~:text= are text fragments: they ask the browser to scroll to and highlight a phrase, and they need no id at all. Chrome has supported them since version 80, Safari since 16.1 and Firefox since 131 (MDN browser data). If the text isn't found, the page simply opens at the top. A checker shouldn't treat :~:text= as a missing anchor. Only the part before :~: is a normal fragment, so #pricing:~:text=Annual still needs an element with id="pricing" (text fragments spec). lychee can check the text part as well with --include-fragments=text-only or full.
