HLS Troubleshooting Guide

This skill provides guidance for diagnosing and resolving Haskell Language Server (HLS) issues in Claude Code.

Overview

HLS provides LSP features for Haskell development: diagnostics, go-to-definition, completions, hover info, and code actions. When HLS isn't working, these features become unavailable for .hs and .lhs files.

Quick Check

Before troubleshooting, run the status command to identify the problem:

/hls:status

This performs three checks: PATH availability, version info, and startup test.

Progressive Troubleshooting

Diagnose issues from simple to complex. Most problems fall into one of three levels.

Level 1: HLS Not Found in PATH

Symptoms:

• /hls:status reports PATH check failed
• "command not found" errors
• No LSP features available

Diagnosis:

Check if HLS is installed:

which haskell-language-server-wrapper

Common Fixes:

1. Install via GHCup (recommended):

   ghcup install hls
   

2. Add GHCup to PATH - Add to shell config (.bashrc, .zshrc):

   export PATH="$HOME/.ghcup/bin:$PATH"
   

3. Verify installation location - Check common paths:

   • ~/.ghcup/bin/haskell-language-server-wrapper
   • ~/.local/bin/haskell-language-server-wrapper
   • ~/.cabal/bin/haskell-language-server-wrapper

4. Restart Claude Code after PATH changes

Level 2: HLS Started But Unresponsive

Symptoms:

• /hls:status PATH check passes but startup test fails
• HLS process visible but no LSP responses
• Long delays before features appear

Diagnosis:

Check if HLS process is running:

ps aux | grep haskell-language-server

Check system resources:

# Memory usage
free -h

# CPU usage
top -b -n 1 | head -20

Common Fixes:

1. Wait for initial indexing - HLS may take several minutes on first load for large projects

2. Check GHC version compatibility - HLS version must match project's GHC:

   haskell-language-server-wrapper --version
   ghc --version
   

   Consult references/hls-docs.xml for the GHC version support matrix.

3. Kill stuck processes:

   pkill -f haskell-language-server
   

4. Check available memory - HLS requires significant RAM for large projects. Consider:

   • Closing other applications
   • Increasing swap space
   • Using a smaller project subset

5. Review HLS logs - Enable debug logging:

   claude --enable-lsp-logging
   

   Logs written to ~/.claude/debug/

Level 3: HLS Running But LSP Commands Failing

Symptoms:

• /hls:status all checks pass
• Some features work but others don't
• Intermittent errors or partial responses

Diagnosis:

Test specific LSP features manually. Check project configuration:

# Look for hie.yaml
ls -la hie.yaml

# Check cabal/stack files
ls -la *.cabal cabal.project stack.yaml 2>/dev/null

Common Fixes:

1. Verify project builds - HLS requires a buildable project:

   cabal build    # or
   stack build
   

   Fix any compilation errors first.

2. Check hie.yaml configuration - For multi-component projects, HLS needs to know which component each file belongs to. Generate implicit config:

   gen-hie > hie.yaml
   

   See references/hls-docs.xml for hie.yaml configuration details.

3. Cradle errors - If HLS reports cradle loading failures:

   • Ensure cabal.project or stack.yaml exists at project root
   • Run cabal update to refresh package index
   • Check for syntax errors in cabal files

4. Enable verbose logging for detailed diagnostics:

   claude --enable-lsp-logging
   

   Check ~/.claude/debug/ for HLS communication logs.

5. Plugin-specific issues - Some HLS plugins may fail independently. Consult references/hls-docs.xml for plugin configuration.

Platform-Specific Notes

Windows

• Use where instead of which for PATH checks
• PATH separator is ; not :
• Common install location: %APPDATA%\ghcup\bin

macOS

• GHCup installs to ~/.ghcup/bin
• May need to allow in System Preferences > Security if blocked

Linux

• GHCup installs to ~/.ghcup/bin
• Ensure glibc compatibility for prebuilt binaries

When to Consult Reference Documentation

For detailed information beyond this troubleshooting guide:

• HLS configuration and features: See references/hls-docs.xml
• GHC version issues and compiler errors: See references/ghc-user.xml
• Cabal project setup and build issues: See references/cabal-docs.xml

These references contain comprehensive documentation for complex issues not covered here.

Summary Checklist

When HLS isn't working:

1. Run /hls:status for quick diagnosis
2. Level 1: Check PATH and installation
3. Level 2: Check process state and resources
4. Level 3: Check project configuration and builds
5. Enable --enable-lsp-logging for detailed debugging
6. Consult reference docs for complex issues