Troubleshooting

This guide helps you resolve common issues when checking links with Linkspector.

Common Issues

Configuration file not found

Problem: Linkspector displays “Configuration file not found. Using default configuration.”Cause: No .linkspector.yml file exists in your current directory, or you specified a custom config path that doesn’t exist.Solutions:

Create a .linkspector.yml file in your project root:
```
dirs:
  - .
useGitIgnore: true
```
If using a custom config path, verify it’s correct:
```
linkspector check --config /path/to/config.yml
```
Use the default configuration without creating a file (checks all .md files in current directory).

The default configuration checks all Markdown files in the current directory while respecting .gitignore rules.

Git is not installed or not found

Problem: Error message: “Git is not installed or not found in the system path.”Cause: You have modifiedFilesOnly: true in your configuration, but Git is not available.Solutions:

Install Git on your system:
- macOS: brew install git
- Ubuntu/Debian: sudo apt-get install git
- Windows: Download from git-scm.com
Verify Git is in your PATH:
```
git --version
```
Disable modifiedFilesOnly if you don’t need this feature:
```
modifiedFilesOnly: false
```

The modifiedFilesOnly feature requires Git and will fail in CI environments without proper Git setup.

Empty or invalid configuration file

Problem: Error: “The configuration file is empty” or “Failed to parse the YAML content.”Cause: Your .linkspector.yml file is empty, contains invalid YAML, or has no valid properties.Solutions:

Check your YAML syntax is valid:

# Bad - empty file

# Bad - no properties
{}

# Good - valid configuration
dirs:
  - .

Validate YAML syntax using an online validator or editor plugin.
Ensure at least dirs or files is specified:
```
files:
  - README.md
  - docs/guide.md
```

Use a YAML linter or editor extension to catch syntax errors before running Linkspector.

No modified files to check

Problem: Message: “No modified files to check, skipping checking.”Cause: You have modifiedFilesOnly: true enabled, but no Markdown files were changed in the last commit.Solutions:

To check all files, set modifiedFilesOnly: false:
```
modifiedFilesOnly: false
```

Verify your file extensions are configured correctly:

fileExtensions:
  - md
  - mdx
  - adoc

Check that modified files match your dirs and files configuration.

This is not an error - it’s expected behavior when no relevant files changed.

SSL/TLS certificate errors

Problem: Links fail with net::ERR_SSL_VERSION_OR_CIPHER_MISMATCH or similar SSL errors.Cause: The target website has SSL/TLS configuration issues, outdated certificates, or incompatible cipher suites.Solutions:

Verify the link works in a browser - if it doesn’t, the link is genuinely broken.
Check if the website requires specific TLS versions or has certificate issues.

Add the pattern to ignorePatterns if you need to skip it:

ignorePatterns:
  - pattern: '^https://problematic-site\.com/.*$'

Contact the website owner to fix their SSL configuration.

Don’t ignore SSL errors for your own documentation - fix the underlying certificate issues instead.

Rate limiting or connection timeouts

Problem: Many links fail with timeout errors or 429 status codes (Too Many Requests).Cause: You’re checking too many links from the same domain too quickly, or the target server is slow.Solutions:

Use aliveStatusCodes to treat 429 as valid if temporary:

aliveStatusCodes:
  - 200
  - 201
  - 204
  - 429  # Temporarily accept rate limited

Check links in smaller batches:
```
dirs:
  - ./docs/chapter1
```

Add problematic domains to ignorePatterns for known rate-limited sites:

ignorePatterns:
  - pattern: '^https://rate-limited-api\.example\.com/.*$'

Run checks during off-peak hours or less frequently.

Consider using modifiedFilesOnly: true to reduce the number of links checked per run.

Authentication required (401/403 errors)

Problem: Links return 401 Unauthorized or 403 Forbidden errors.Cause: The target URL requires authentication, but no credentials are provided.Solutions:

Add HTTP headers with authentication tokens:

httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: Bearer ${API_TOKEN}

Store credentials in environment variables:
```
# .env file
API_TOKEN=your-token-here
```

For internal/private links, use ignorePatterns:

ignorePatterns:
  - pattern: '^https://internal\.company\.com/.*$'

Replace private links with public alternatives if available.

Environment variable substitution uses the ${VARIABLE_NAME} syntax in your config file.

Relative links not resolving correctly

Problem: Relative links like ./guide.md or ../index.md are reported as broken even though they exist.Cause: Missing or incorrect baseUrl configuration, or files are not in expected locations.Solutions:

Set a baseUrl for checking relative links:
```
baseUrl: https://docs.example.com
```
Verify file paths match your directory structure:
```
ls -la docs/guide.md
```

Ensure dirs configuration includes all relevant directories:

dirs:
  - ./docs
  - ./guides
  - ./tutorials

Check file extensions are included in fileExtensions:
```
fileExtensions:
  - md
  - mdx
```

Use absolute paths or set baseUrl to avoid relative path resolution issues.

JSON output is malformed

Problem: JSON output with --json flag is not valid JSON or missing expected fields.Cause: Internal validation/fixing failed, or unexpected data structure.Solutions:

Check stderr for validation messages:
```
linkspector check --json 2>errors.log
```
Validation errors are logged to stderr while valid JSON goes to stdout:
```
linkspector check --json > output.json 2> validation.log
```

Update to the latest version of Linkspector:

npm install -g @umbrelladocs/linkspector@latest

Report the issue with your configuration if problem persists.

Linkspector automatically validates and fixes RDJSON output. Check stderr for details about applied fixes.

--json and --showstat cannot be used together

Problem: Error: “The —json and —showstat options cannot be used together.”Cause: Both output format flags were specified in the same command.Solutions:

Choose one output format per run:

# For JSON output
linkspector check --json

# For statistics
linkspector check --showstat

Run separate commands if you need both formats:

linkspector check --json > results.json
linkspector check --showstat

These options are mutually exclusive by design - choose the format that matches your use case.

False positives for working links

Problem: Links that work in browsers are reported as broken by Linkspector.Cause: The site may be blocking automated tools, using JavaScript redirects, or has bot protection.Solutions:

Linkspector uses Puppeteer (headless Chrome) to reduce false positives. Ensure Chrome dependencies are installed.

Add custom HTTP headers to mimic browser requests:

httpHeaders:
  - url:
      - https://example.com
    headers:
      User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)

Configure redirect handling:
```
followRedirects: true
```

Add to ignorePatterns as a last resort:

ignorePatterns:
  - pattern: '^https://problematic-site\.com/.*$'

Linkspector’s use of Puppeteer significantly reduces false positives compared to simple HTTP checkers.

Debugging Tips

Enable Verbose Output

Check what Linkspector is processing by monitoring the spinner messages:

linkspector check
# Shows: Checking README.md... Checking docs/guide.md...

Isolate the Problem

Test specific files to narrow down issues:

# Temporary config for debugging
files:
  - problematic-file.md

Validate Configuration

Before running the full check, verify your configuration is valid:

# Check if config file loads without errors
linkspector check --config .linkspector.yml

Check Git Status

If using modifiedFilesOnly, verify Git is working:

git diff --name-only HEAD HEAD~1

Test Individual Links

Use curl or browser developer tools to test specific failing links:

curl -I https://example.com/broken-link

Review Statistics

Use statistics mode to understand link distribution:

linkspector check --showstat

This helps identify patterns (e.g., if all HTTP links fail, it might be a network issue).

Performance Optimization

Reduce scope of checks

Strategy: Check only necessary files

# Check specific directories
dirs:
  - ./docs
  - ./guides

# Exclude large or irrelevant directories
excludedDirs:
  - ./node_modules
  - ./vendor
  - ./build

# Use modified files only in CI
modifiedFilesOnly: true

Use ignore patterns strategically

Strategy: Skip known problematic or irrelevant links

ignorePatterns:
  # Skip localhost links
  - pattern: '^https?://localhost.*$'
  
  # Skip example domains
  - pattern: '^https?://example\.(com|org|net).*$'
  
  # Skip internal/development URLs
  - pattern: '^https?://.*\.local/.*$'

Configure alive status codes

Strategy: Accept more status codes as valid

aliveStatusCodes:
  - 200
  - 201
  - 204
  - 301  # Permanent redirect
  - 302  # Temporary redirect
  - 307  # Temporary redirect (preserves method)
  - 308  # Permanent redirect (preserves method)

Be cautious adding redirect codes - use followRedirects: true instead when possible.

Respect .gitignore rules

Strategy: Automatically exclude unnecessary files

useGitIgnore: true

This skips checking links in files already excluded by your .gitignore:

node_modules/
Build artifacts
Temporary files
IDE configurations

Getting Help

If you’ve tried these solutions and still experience issues:

Check the README - Review configuration options
Search existing issues - Someone may have encountered the same problem: GitHub Issues
Report a bug - Open a new issue with:
- Your .linkspector.yml configuration
- Complete error message
- Linkspector version (linkspector --version)
- Operating system and Node.js version
Ask for help - Reach out to the community or maintainers

GitHub Issues

Report bugs and request features

NPM Package

Check for updates and version history

Get Started

Commands

Configuration

Guides

Reference

Common Issues

Debugging Tips

Enable Verbose Output

Isolate the Problem

Validate Configuration

Check Git Status

Test Individual Links

Review Statistics

Performance Optimization

Getting Help

GitHub Issues

NPM Package

Build docs developers (and LLMs) love

Get Started

Commands

Configuration

Guides

Reference

​Common Issues

​Debugging Tips

​Enable Verbose Output

​Isolate the Problem

​Validate Configuration

​Check Git Status

​Test Individual Links

​Review Statistics

​Performance Optimization

​Getting Help

GitHub Issues

NPM Package

Build docs developers (and LLMs) love

Common Issues

Debugging Tips

Enable Verbose Output

Isolate the Problem

Validate Configuration

Check Git Status

Test Individual Links

Review Statistics

Performance Optimization

Getting Help