---
title: "Troubleshooting Nuxt Link Checker"
description: "Solve common link checking issues and create reproductions for bug reports."
canonical_url: "https://nuxtseo.com/docs/link-checker/getting-started/troubleshooting"
last_updated: "2026-05-06T18:45:06.645Z"
---

## Common Issues

### Links Not Being Detected

If links aren't being detected during scans:

1. Ensure `runOnBuild` is not set to `false` in your config
2. Check that the page is being prerendered (SSG) or SSR'd
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](/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

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

### DevTools Integration Not Working

If live inspections aren't appearing:

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

## Debugging Tools

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

## 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)