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 is prerendered. The build scan reads only prerendered pages
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 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

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 playgrounds:

• Basic

Debugging Tools

• Meta Tag Checker - Verify page metadata after fixing broken links
• XML Sitemap Validator - Cross-reference broken links with your sitemap