Troubleshooting Nuxt Link Checker

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 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. Ensure Nuxt DevTools is enabled in your config
2. Check that showLiveInspections is not set to false
3. Restart your dev server after config changes

Debugging Tools

• Meta Tag Checker - Verify page metadata after fixing broken links
• 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 playgrounds:

• Basic