VS Code extension hangs

Common symptoms with the VS Code extension for .ccr files:

• No auto-completion for schema properties.
• The status bar item shows an error icon next to "CodeCharter"; hovering it reveals details such as "serverPath not set and CLI not found in PATH".
• CodeCharter: Analyze workspace (.sln/.csproj) fails with the message "CodeCharter CLI not found. Set "codecharter.serverPath" in settings."

Note: syntax highlighting for .ccr files comes from the extension itself and works even when the language server is not running. If highlighting is missing, the extension is not installed or not active, which is a different problem.

Here is the usual debugging sequence.

1. Open the Output panel

View → Output, select "CodeCharter" from the dropdown. This shows the CLI invocation and all LSP messages. You can also click the CodeCharter status bar item or run CodeCharter: Show language server output from the command palette to open the same channel.

Look for:

• [lsp] starting: <path> lsp with the resolved CLI path
• [lsp] start failed: ... or stderr output from the CLI
• [activate] resolved serverPath = <none> if no CLI was found

2. Check CLI availability

If codecharter.serverPath is not set, the extension searches the PATH for codecharter, CodeCharter.Cli, and CodeCharter.Cli.exe. If that does not work:

codecharter --version

If that gives "command not found", set codecharter.serverPath in the VS Code settings to the full path. The value supports the ${workspaceFolder} and ${userHome} variables:

{
  "codecharter.serverPath": "/usr/local/bin/codecharter"
}

or on Windows (the default per-user install goes to %LOCALAPPDATA%\Programs\CodeCharter; an elevated all-users install goes to C:\Program Files\CodeCharter):

{
  "codecharter.serverPath": "${userHome}\\AppData\\Local\\Programs\\CodeCharter\\codecharter.exe"
}

On Windows you can also re-run the installer: it can install the VS Code extension and set codecharter.serverPath automatically.

3. Permissions on Linux and macOS

If you installed the CLI manually, the execute bit is sometimes forgotten:

chmod +x /opt/codecharter/codecharter

The Output panel will typically show a permission-denied message in this case.

4. Restart the language server

In the command palette: CodeCharter: Restart language server.

5. Check codecharter restore on startup

If your repository contains a codecharter.yml that declares profiles, the extension runs codecharter restore on activation before starting the language server. A slow or failing restore can look like a hang. Check the Output panel for [restore] lines. If the extension warns that the lockfile or rule cache is out of date, use the "Run restore" action in the notification.

6. Extension version

code --list-extensions --show-versions | grep -i codecharter

Compare with the current release in the portal. If your version is significantly older: reinstall the VSIX. Note that the extension requires VS Code 1.85 or newer; on an older VS Code the VSIX cannot be installed at all.

7. Enable tracing

For detailed LSP traffic:

{
  "codecharter.trace.server": "verbose"
}

Then open the Output panel and go through the LSP log.

If nothing helps

[email protected] with:

• VS Code version
• CodeCharter extension version
• CodeCharter CLI version (codecharter --version)
• Output panel logs as an attachment
• Operating system and architecture