Troubleshooting

Common Issues

Extension not activating

Symptoms: No diagnostics appear; status bar items are missing.

Solutions:

  1. Check the VS Code Output panel (View > Output > Language Check) for error messages.

  2. Ensure the active file is a supported type (Markdown, HTML, or LaTeX).

  3. Run Language Check: Check Current Document from the Command Palette.

Core binary not found

Symptoms: Error message about missing binary on activation.

Solutions:

  1. Click Download when prompted to auto-download the binary.

  2. Or download manually from GitHub Releases.

  3. Set a custom path: languageCheck.core.binaryPath in VS Code settings.

LanguageTool connection errors

Symptoms: Only Harper diagnostics appear; LT errors in output.

Solutions:

  1. Start a local LanguageTool server: docker compose up -d

  2. Verify the URL in config: engines.languagetool_url

  3. Or disable LT: set engines.languagetool: false

High memory usage

Solutions:

  1. Enable High Performance Mode to disable LT and external providers.

  2. Set performance.max_file_size to skip large files.

  3. Add large directories to exclude patterns.

SpeedFix panel is blank

Solutions:

  1. Reload the VS Code window (Ctrl+Shift+P > Reload Window).

  2. Check that the webview assets exist in the extension directory.

Debug Tools

Protobuf Trace

Enable message tracing to see all communication between the extension and core:

  1. Run Language Check: Toggle Protobuf Trace

  2. Run Language Check: Show Protobuf Trace to open the output channel

  3. Check and fix a document to see traced messages

Inspector Panel

Open the Inspector debug panel for advanced diagnostics:

  1. Run Language Check: Open Inspector

  2. View the AST structure, extracted prose ranges, and pipeline latency

Core Channel Switching

Switch between different core binary builds:

  1. Run Language Check: Switch Core Binary

  2. Choose Stable, Canary, or Dev

  3. Dev builds include debug symbols and verbose logging

Reporting Issues

Tip

Including all of the items below helps us diagnose the problem faster.

  1. VS Code version (Help > About)

  2. Extension version (Extensions panel)

  3. Core binary version (from output channel)

  4. Protobuf trace output (see above)

  5. Minimal reproduction file