lua-nvim/LSP_TROUBLESHOOTING_GUIDE.md

LSP Troubleshooting and Performance Guide

Overview

This guide addresses the LSP errors and image freezing issues you've been experiencing during file searches in Neovim.

Problems Solved

1. LSP Errors on Non-Text Files

Problem: LSP servers were trying to process image files (PNG, SVG, etc.), video files, and other binary files, causing errors.

Solution: Added comprehensive file type filtering that prevents LSP from attaching to non-text files.

2. Image Freezing During Search

Problem: When searching for files, image files would freeze the preview window indefinitely.

Solution: Enhanced Telescope configuration with file filtering and optimized preview settings.

3. Slow Leader Key Response

Problem: Leader key commands (like <leader>ff, <leader>fs) were slow to respond.

Solution: Reduced timeout settings and optimized completion performance.

New Keymaps

Performance Monitoring

• <leader>pp - Check overall performance
• <leader>po - Check plugin performance
• <leader>pb - Optimize current buffer

LSP Troubleshooting

• <leader>pl - Check LSP health
• <leader>pr - Restart LSP for current buffer

Safe File Searching (Recommended)

• <leader>ff - Find files (safe - prevents LSP errors)
• <leader>fs - Live grep (safe)
• <leader>fg - Git files (safe)
• <leader>ft - Text files only

Regular Search (Use with Caution)

• <leader>fF - Find files (all file types)

File Types Automatically Filtered

Images (Prevent LSP errors)

• PNG, JPG, JPEG, GIF, SVG, ICO, BMP, WebP, TIFF, TGA

Videos (Prevent freezing)

• MP4, AVI, MOV, WMV, FLV, WebM, MKV, M4V, 3GP

Audio (Prevent LSP errors)

• MP3, WAV, FLAC, AAC, OGG, M4A, WMA

Documents (Prevent LSP errors)

• PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, ODT, ODS, ODP

Archives (Prevent LSP errors)

• ZIP, RAR, 7Z, TAR, GZ, BZ2, XZ, LZMA

Binaries (Prevent LSP errors)

• EXE, DLL, SO, DYLD, BIN, APP, DMG, DEB, RPM

Other Problematic Files

• LOCK, LOG, TMP, TEMP, CACHE, BAK, BACKUP

Performance Optimizations Applied

LSP Configuration

• File filtering: Only text files get LSP services
• Error handling: Graceful handling of LSP failures
• Timeouts: 5-second timeout for LSP requests
• Debouncing: 150ms debounce for text changes
• Diagnostics: Reduced diagnostic updates

Telescope Configuration

• File filtering: Automatic exclusion of problematic files
• Preview optimization: Disabled preview for non-text files
• Search optimization: Skip heavy directories (node_modules, vendor, etc.)
• Performance flags: Enhanced caching and sorting

General Performance

• Reduced timeouts: Faster leader key response
• Optimized scrolling: Reduced scrolloff for smoother movement
• Memory management: Better memory usage patterns
• Startup optimization: Deferred heavy operations

Troubleshooting Steps

If You Still Experience LSP Errors

1. Check LSP Health

   <leader>pl
   

2. Restart LSP for Current Buffer

   <leader>pr
   

3. Check Performance

   <leader>pp
   

4. Use Safe File Search

   • Always use <leader>ff instead of <leader>fF
   • This prevents LSP from processing problematic files

If Images Still Freeze

1. Check File Extensions

   • Ensure the file has a text-based extension
   • Use <leader>ft for text-only file search

2. Optimize Current Buffer

   <leader>pb
   

3. Check Plugin Performance

   <leader>po
   

Advanced Configuration

Custom File Filtering

You can modify the file filtering in lua/cargdev/plugins/lsp/lspconfig.lua:

local non_text_extensions = {
  -- Add or remove extensions as needed
  "png", "jpg", "jpeg", "gif", "svg",
  -- ... other extensions
}

Telescope Customization

Modify the file filter in lua/cargdev/plugins/telescope.lua:

local function filter_files(entry)
  -- Customize filtering logic here
  local filename = entry.filename or entry.value
  -- ... your custom logic
end

Best Practices

1. Always Use Safe Search

• <leader>ff for file finding
• <leader>fs for text searching
• Avoid <leader>fF unless you specifically need all file types

2. Monitor Performance

• Use <leader>pp regularly to check for issues
• Monitor LSP health with <leader>pl

3. Optimize Large Files

• Use <leader>pb for files over 10,000 lines
• Consider disabling heavy features for very large files

4. Keep LSP Healthy

• Restart LSP with <leader>pr if you experience issues
• Check for LSP errors in the performance report

Expected Results

After applying these optimizations:

• ✅ No more LSP errors on image/video/binary files
• ✅ No more image freezing during file searches
• ✅ Faster leader key response (reduced from 500ms to 200ms)
• ✅ Smoother scrolling and UI performance
• ✅ Better memory usage and startup times
• ✅ Automatic file type filtering to prevent issues

Support

If you continue to experience issues:

1. Run <leader>pp to get a detailed performance report
2. Check LSP health with <leader>pl
3. Use the safe file search commands (<leader>ff, <leader>fs)
4. Consider restarting LSP with <leader>pr

The optimizations maintain all your functionality while significantly improving stability and performance.