Invalid Hash

The invalid hash error indicates that an internal link points to an existing page, but the hash fragment, the part after #, does not match any heading or element ID on that page. For example, in /guides/usage/#overview, #overview is the hash fragment. Common causes include typos in the hash, links to headings that were renamed or removed, and links to hashes that do not exist on the target page.

If you prefer to only validate that pages exist but ignore hashes, you can disable this error using the errorOnInvalidHashes option. This can be useful in large documentation sites with many contributors, where keeping hashes fully up to date may be difficult, and hash validation may happen on a different schedule, for example once a week.

Example

For example, given the following project structure:

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguides/

        • usage.mdx
      • getting-started.md

With the following content in src/content/docs/guides/usage.mdx:

src/content/docs/guides/usage.mdx

---
title: Usage
---

## Overview

Some content.

## Setup

Some content.

And this content in src/content/docs/getting-started.md:

src/content/docs/getting-started.md

---
title: Getting Started
---

## Next Steps

- [Usage overview](/guides/usage/#overveiw)
- [Setup guide](/guides/usage/#setup)
- [Troubleshooting](#troubleshooting)

## Updating

Some content.

A production build would report the following errors:

astro build

  ╭─ getting-started.md
  ·
7 | /guides/usage/#overveiw
  ·                      ╰── invalid hash
9 | #troubleshooting
  ·               ╰── invalid hash

╭─                                ─╮
· Found 2 invalid links in 1 file. ·
╰─                                ─╯

How to fix

To fix invalid hash errors, update each broken hash so it matches an existing heading or element ID.

For the example above, you would:

• Update /guides/usage/#overveiw to /guides/usage/#overview so the hash matches the existing heading ID.
• Update #troubleshooting to match an existing heading or element ID in src/content/docs/getting-started.md, or create the missing heading if it should exist.