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