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:

code

/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:

bash

which haskell-language-server-wrapper

Common Fixes:

•
Install via GHCup (recommended):
bash
```
ghcup install hls
```
•
Add GHCup to PATH - Add to shell config (.bashrc, .zshrc):
bash
```
export PATH="$HOME/.ghcup/bin:$PATH"
```
•
Verify installation location - Check common paths:
- •~/.ghcup/bin/haskell-language-server-wrapper
- •~/.local/bin/haskell-language-server-wrapper
- •~/.cabal/bin/haskell-language-server-wrapper
•
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:

bash

ps aux | grep haskell-language-server

Check system resources:

bash

# Memory usage
free -h

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

Common Fixes:

•
Wait for initial indexing - HLS may take several minutes on first load for large projects
•
Check GHC version compatibility - HLS version must match project's GHC:
bash
```
haskell-language-server-wrapper --version
ghc --version
```
Consult references/hls-docs.xml for the GHC version support matrix.
•
Kill stuck processes:
bash
```
pkill -f haskell-language-server
```
•
Check available memory - HLS requires significant RAM for large projects. Consider:
- •Closing other applications
- •Increasing swap space
- •Using a smaller project subset
•
Review HLS logs - Enable debug logging:
bash
```
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:

bash

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

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

Common Fixes:

•
Verify project builds - HLS requires a buildable project:
bash
```
cabal build    # or
stack build
```
Fix any compilation errors first.
•
Check hie.yaml configuration - For multi-component projects, HLS needs to know which component each file belongs to. Generate implicit config:
bash
```
gen-hie > hie.yaml
```
See references/hls-docs.xml for hie.yaml configuration details.
•
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
•
Enable verbose logging for detailed diagnostics:
bash
```
claude --enable-lsp-logging
```
Check ~/.claude/debug/ for HLS communication logs.
•
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:

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