---
title: "Troubleshooting Nuxt Link Checker · Nuxt Link Checker · Nuxt SEO"
canonical_url: "https://nuxtseo.com/docs/link-checker/getting-started/troubleshooting"
last_updated: "2026-08-16T09:50:35.647Z"
meta:
  description: "Solve common link checking issues and create reproductions for bug reports."
  "og:description": "Solve common link checking issues and create reproductions for bug reports."
  "og:title": "Troubleshooting Nuxt Link Checker · Nuxt Link Checker · Nuxt SEO"
---

Nuxt SEO on GitHub

Switch to Link CheckerSwitch to Nuxt SEOSwitch to RobotsSwitch to SitemapSwitch to OG ImageSwitch to Schema.orgSwitch to SEO UtilsSwitch to Site ConfigSwitch to Skew ProtectionSwitch to AI Ready

**Getting Started**

# **Troubleshooting Nuxt Link Checker**

## Debugging

### Link Detection Issues

If scans don't detect links:

1. Ensure `**runOnBuild**` is not set to `**false**` in your config
2. Check that the page uses prerendering (SSG) or SSR
3. Verify links use standard `**<a>**` or `**<NuxtLink>**` elements

### False Positives on Valid Links

Some links may be incorrectly flagged:

- **Rate limiting**: External services may block rapid requests during scans
- **Auth-protected pages**: Links requiring authentication will fail validation
- **Dynamic routes**: Routes with parameters need proper prerendering

To exclude specific links, see the [**~~Exclude Links~~**](https://nuxtseo.com/docs/link-checker/guides/exclude-links) guide.

### Build Failing Due to Broken Links

If your CI is failing:

1. Review the generated report to identify actual broken links
2. Use `**failOnError: false**` temporarily while fixing issues
3. Consider using `**skipInspections**` for rules causing false positives

nuxt.config.ts

```ts
export default defineNuxtConfig({
  linkChecker: {
    failOnError: false, // Temporarily disable to unblock builds
  },
})
```

### DevTools Integration Not Working

If live inspections aren't appearing:

1. Enable Nuxt DevTools in your config
2. Enable `**showLiveInspections**` in your config (it is `**false**` by default)
3. Restart your dev server after config changes

## Submitting an Issue

When submitting an issue, it's important to provide as much information as possible.

The easiest way to do this is to create a minimal reproduction using the [**~~StackBlitz~~**](https://stackblitz.com) playgrounds:

- [**~~Basic~~**](https://stackblitz.com/edit/nuxt-starter-r2wzt1?file=nuxt.config.ts)

## Debugging Tools

- [**~~Meta Tag Checker~~**](https://nuxtseo.com/tools/meta-tag-checker) - Verify page metadata after fixing broken links
- [**~~XML Sitemap Validator~~**](https://nuxtseo.com/tools/xml-sitemap-validator) - Cross-reference broken links with your sitemap

**Was this page helpful?**

### **Related **

[**Exclude Links**](https://nuxtseo.com/docs/link-checker/guides/exclude-links)

[**Inspection Rules**](https://nuxtseo.com/docs/link-checker/guides/rules)

[**Nuxt SEO Troubleshooting**](https://nuxtseo.com/docs/nuxt-seo/getting-started/troubleshooting)

[**Installation** Get started with Nuxt Link Checker by installing the dependency to your project.](https://nuxtseo.com/docs/link-checker/getting-started/installation) [**Inspection Rules** Find out what rules are run when checking your links and why they exist.](https://nuxtseo.com/docs/link-checker/guides/rules)