Language Server Protocol (LSP) Support
Qwen Code provides native Language Server Protocol (LSP) support, enabling advanced code intelligence features like go-to-definition, find references, diagnostics, and code actions. This integration allows the AI agent to understand your code more deeply and provide more accurate assistance.
Overview
LSP support in Qwen Code works by connecting to language servers that understand your code. Once you configure servers via .lsp.json (or extensions), Qwen Code can start them and use them to:
- Navigate to symbol definitions
- Find all references to a symbol
- Get hover information (documentation, type info)
- View diagnostic messages (errors, warnings)
- Access code actions (quick fixes, refactorings)
- Analyze call hierarchies
Quick Start
LSP is an experimental feature in Qwen Code. To enable it, set tools.lspEnabled in your user settings.json:
{
"tools": {
"lspEnabled": true
}
}Hosts that take command line flags can use --experimental-lsp instead — the two are equivalent, and QWEN_CODE_ENABLE_LSP=1 / QWEN_CODE_DISABLE_LSP=1 override both (disable wins). Only the operator’s environment or a home-scoped .env can set those two variables; a project .env or a settings.env value is ignored silently. The setting is read at startup only, so changing it needs a restart; it is honored from the user, system and system-defaults scopes, never from a workspace .qwen/settings.json, because enabling it lets a session spawn language servers with your own permissions. LSP is refused outright in safe mode (--safe-mode / QWEN_CODE_SAFE_MODE=1), bare mode, a read-only agent host, an SSH workspace and a provisional workspace, because those modes distrust the workspace content that declares the servers. Declaring servers stays a workspace/extension decision.
LSP servers are configuration-driven. You must define them in .lsp.json (or via extensions) for Qwen Code to start them.
Prerequisites
You need to have the language server for your programming language installed:
| Language | Language Server | Install Command |
|---|---|---|
| TypeScript/JavaScript | typescript-language-server | npm install -g typescript-language-server typescript |
| Python | pylsp | pip install python-lsp-server |
| Go | gopls | go install golang.org/x/tools/gopls@latest |
| Rust | rust-analyzer | Installation guide |
| C/C++ | clangd | Install LLVM/clangd via your package manager |
| Java | jdtls | Install JDTLS and a JDK |
| C# | roslyn-language-server | dotnet tool install --global roslyn-language-server --prerelease (.NET 10+) |
Configuration
.lsp.json File
You can configure language servers using a .lsp.json file in your project root. Each top-level key is a language identifier, and its value is the server configuration object.
Basic format:
{
"typescript": {
"command": "typescript-language-server",
"args": ["--stdio"],
"extensionToLanguage": {
".ts": "typescript",
".tsx": "typescriptreact",
".js": "javascript",
".jsx": "javascriptreact"
}
}
}C/C++ (clangd) configuration
Dependencies:
- clangd (LLVM) must be installed and available in PATH.
- A compile database (
compile_commands.json) orcompile_flags.txtis required for accurate results.
Example:
{
"cpp": {
"command": "clangd",
"args": [
"--background-index",
"--clang-tidy",
"--header-insertion=iwyu",
"--completion-style=detailed"
]
}
}Java (jdtls) configuration
Dependencies:
- JDK installed and available in PATH (
java). - JDTLS installed and available in PATH (
jdtls).
Example:
{
"java": {
"command": "jdtls",
"args": ["-configuration", ".jdtls-config", "-data", ".jdtls-workspace"]
}
}C# (Roslyn) configuration
Dependencies:
- .NET 10 runtime or later (
dotnet --version). - The
roslyn-language-serverglobal tool:dotnet tool install --global roslyn-language-server --prerelease. See the Roslyn language server README for current prerequisites and options.
Example:
{
"csharp": {
"command": "roslyn-language-server",
"args": ["--stdio", "--autoLoadProjects"],
"extensionToLanguage": {
".cs": "csharp"
}
}
}On Windows the global tool is installed as a cmd shim under
%USERPROFILE%\.dotnet\tools. Qwen Code starts servers without a shell, so a
bare roslyn-language-server is found by where but fails to spawn. Use the
shell form there:
{
"csharp": {
"command": "cmd",
"args": ["/c", "roslyn-language-server", "--stdio", "--autoLoadProjects"],
"extensionToLanguage": {
".cs": "csharp"
}
}
}An absolute path to the real executable under
%USERPROFILE%\.dotnet\tools\.store\roslyn-language-server\<version>\...
works as well.
Configuration Options
Required Fields
| Option | Type | Description |
|---|---|---|
command | string | Command to start the LSP server. Supports bare command names resolved via PATH (e.g. clangd) and absolute paths (e.g. /opt/llvm/bin/clangd) |
Optional Fields
| Option | Type | Default | Description |
|---|---|---|---|
args | string[] | [] | Command line arguments |
transport | string | "stdio" | Transport type: stdio, tcp, or socket |
env | object | - | Environment variables |
initializationOptions | object | - | LSP initialization options |
settings | object | - | Server settings via workspace/didChangeConfiguration |
extensionToLanguage | object | - | Maps file extensions to language identifiers |
workspaceFolder | string | - | Override workspace folder (must be within project root) |
startupTimeout | number | 10000 | Startup timeout in milliseconds |
shutdownTimeout | number | 5000 | Shutdown timeout in milliseconds |
restartOnCrash | boolean | false | Auto-restart on crash |
maxRestarts | number | 3 | Maximum restart attempts |
trustRequired | boolean | true | Require trusted workspace |
TCP/Socket Transport
For servers that use TCP or Unix socket transport:
{
"remote-lsp": {
"transport": "tcp",
"socket": {
"host": "127.0.0.1",
"port": 9999
},
"extensionToLanguage": {
".custom": "custom"
}
}
}Available LSP Operations
Qwen Code exposes LSP functionality through the unified lsp tool. Here are the available operations:
Location-based operations (goToDefinition, findReferences, hover, goToImplementation, and prepareCallHierarchy) require an exact filePath + line + character position. If you do not know the exact position, use workspaceSymbol or documentSymbol first to locate the symbol.
Code Navigation
Go to Definition
Find where a symbol is defined.
Operation: goToDefinition
Parameters:
- filePath: Path to the file
- line: Line number (1-based)
- character: Column number (1-based)Find References
Find all references to a symbol.
Operation: findReferences
Parameters:
- filePath: Path to the file
- line: Line number (1-based)
- character: Column number (1-based)
- includeDeclaration: Include the declaration itself (optional)Go to Implementation
Find implementations of an interface or abstract method.
Operation: goToImplementation
Parameters:
- filePath: Path to the file
- line: Line number (1-based)
- character: Column number (1-based)Symbol Information
Hover
Get documentation and type information for a symbol.
Operation: hover
Parameters:
- filePath: Path to the file
- line: Line number (1-based)
- character: Column number (1-based)Document Symbols
Get all symbols in a document.
Operation: documentSymbol
Parameters:
- filePath: Path to the fileWorkspace Symbol Search
Search for symbols across the workspace.
Operation: workspaceSymbol
Parameters:
- query: Search query string
- limit: Maximum results (optional)Call Hierarchy
Prepare Call Hierarchy
Get the call hierarchy item at a position.
Operation: prepareCallHierarchy
Parameters:
- filePath: Path to the file
- line: Line number (1-based)
- character: Column number (1-based)Incoming Calls
Find all functions that call the given function.
Operation: incomingCalls
Parameters:
- callHierarchyItem: Item from prepareCallHierarchyOutgoing Calls
Find all functions called by the given function.
Operation: outgoingCalls
Parameters:
- callHierarchyItem: Item from prepareCallHierarchyDiagnostics
File Diagnostics
Get diagnostic messages (errors, warnings) for a file.
Operation: diagnostics
Parameters:
- filePath: Path to the fileWorkspace Diagnostics
Get all diagnostic messages across the workspace.
Operation: workspaceDiagnostics
Parameters:
- limit: Maximum results (optional)Code Actions
Get Code Actions
Get available code actions (quick fixes, refactorings) at a location.
Operation: codeActions
Parameters:
- filePath: Path to the file
- line: Start line number (1-based)
- character: Start column number (1-based)
- endLine: End line number (optional, defaults to line)
- endCharacter: End column (optional, defaults to character)
- diagnostics: Diagnostics to get actions for (optional)
- codeActionKinds: Filter by action kind (optional)Code action kinds:
quickfix- Quick fixes for errors/warningsrefactor- Refactoring operationsrefactor.extract- Extract to function/variablerefactor.inline- Inline function/variablesource- Source code actionssource.organizeImports- Organize importssource.fixAll- Fix all auto-fixable issues
Security
Language servers run with your user permissions and can execute code. Servers configured by a workspace’s .lsp.json require explicit folder trust, including their executable availability probes and hot reloads. Enable security.folderTrust.enabled in user settings and trust the directory, or grant workspace trust through your IDE. Disabling folder trust does not authorize workspace LSP configurations, including in YOLO mode.
Trust Controls
- Explicitly Trusted Workspace: Workspace LSP servers start if configured.
- No Explicit Trust: Workspace
.lsp.jsonservers are skipped. The repository cannot override this by settingtrustRequired: falseor declaring an extension source.
After enabling folder trust in user settings, use the startup trust dialog or /trust to trust the directory. Restart after changing the CLI’s trust decision.
Per-Server Trust Override
Installed extensions retain their existing trust policy. An extension can declare trustRequired: false when the host permits LSP discovery in untrusted workspaces. This override is ignored in workspace .lsp.json:
{
"safe-server": {
"command": "safe-language-server",
"args": ["--stdio"],
"trustRequired": false,
"extensionToLanguage": {
".safe": "safe"
}
}
}Troubleshooting
Server Not Starting
- Verify LSP is enabled: Use the
tools.lspEnabledsetting (user, system or system-defaults scope) or the--experimental-lspflag;QWEN_CODE_ENABLE_LSP=1/QWEN_CODE_DISABLE_LSP=1override both (disable wins). Safe mode (--safe-mode,QWEN_CODE_SAFE_MODE=1) and--barerefuse LSP, and/lspis not registered there - Check if the server is installed: Run the command manually (e.g.
clangd --version) to verify - Check the command: The server binary must be in your system
PATH, or specified as an absolute path (e.g./opt/llvm/bin/clangd). Relative paths that escape the workspace are blocked - Check workspace trust: A workspace-declared server starts only in an explicitly trusted folder — enable
security.folderTrust.enabledand trust the folder with/trust, or connect an IDE that reports the workspace as trusted. An IDE report of an untrusted workspace (VS Code Restricted Mode) skips it too, and with folder trust off and no IDE trust the server is skipped rather than admitted. The IDE check is re-evaluated when.lsp.jsonchanges, and the skip appears only in the--debuglog asrequires trusted workspace, skipping - Check logs: Start Qwen Code with
--debug, then search for LSP-related entries in the debug log (see Debugging section below) - Check the process: Run
ps aux | grep <server-name>to verify the server process is running
Slow Performance
- Large projects: Consider excluding
node_modulesand other large directories - Server timeout: Increase
startupTimeoutin server configuration for slow servers
No Results
- Server not ready: The server may still be indexing. For C/C++ projects with clangd, ensure
--background-indexis in the args and acompile_commands.json(orcompile_flags.txt) exists in the project root or a parent directory. Use--compile-commands-dir=<path>if it is in a build subdirectory - File not saved: Save your file for the server to pick up changes
- Wrong language: Check if the correct server is running for your language
- Check the process: Run
ps aux | grep <server-name>to verify the server is actually running
Debugging
LSP does not have a separate debug flag. Enable LSP through the setting (or the flag), then turn on Qwen Code’s normal debug mode:
qwen --debugDebug logs are written to the session debug log directory. To check LSP-related entries:
# Default runtime directory
rg "LSP|Native LSP|clangd|connection closed" ~/.qwen/debug/latest
# Or, without ripgrep:
grep -E "LSP|Native LSP|clangd|connection closed" ~/.qwen/debug/latest
# If QWEN_RUNTIME_DIR is configured
rg "LSP|Native LSP|clangd|connection closed" "$QWEN_RUNTIME_DIR/debug/latest"Useful entries include:
[LSP] ...: Logs emitted by the native LSP service and server manager.[CONFIG] Native LSP status after discovery: ...: LSP server configuration discovered for the session.[CONFIG] Native LSP status after startup: ...: Server startup result, including ready/failed counts.[STATUS] LSP status snapshot for /status: ...: Status snapshot printed when running/statusin debug mode.
You can also run /status in the CLI to see a short LSP summary:
LSP: disabled
LSP: enabled, 1/1 ready
LSP: enabled, 0/1 ready (1 failed)
LSP: enabled, no servers configured
LSP: enabled, status unavailableFor per-server details, run /lsp:
**LSP Server Status**
| Server | Command | Languages | Status |
|--------|---------|-----------|--------|
| clangd | `clangd` | c, cpp | READY |
| pyright | `pyright-langserver` | python | FAILED - startup failed |Common error messages to look for:
command path is unsafe -> relative path escapes workspace, use absolute path or add to PATH
command not found -> server binary not installed or not in PATH
requires trusted workspace -> run /trust first
LSP connection closed -> server started but exited or closed stdio before replying to initializeFor clangd startup failures, verify the server directly from the project root:
clangd --version
clangd --check=/path/to/file.cpp --log=verboseC/C++ projects should usually provide a compile_commands.json or compile_flags.txt. If the compile database is in a build directory, pass it to clangd:
{
"cpp": {
"command": "clangd",
"args": ["--background-index", "--compile-commands-dir=build"]
}
}ps aux | grep clangd # or typescript-language-server, jdtls, etc.Extension LSP Configuration
Extensions can provide LSP server configurations through the lspServers field in their plugin.json. This can be either an inline object or a path to a .lsp.json file. Qwen Code loads these configs when the extension is enabled. The format is the same language-keyed layout used in project .lsp.json files.
Best Practices
- Install language servers globally: This ensures they’re available in all projects
- Use project-specific settings: Configure server options per project when needed via
.lsp.json - Keep servers updated: Update your language servers regularly for best results
- Trust wisely: Only trust workspaces from trusted sources
FAQ
Q: How do I enable LSP?
Use the tools.lspEnabled setting (user, system or system-defaults scope) or the --experimental-lsp flag. QWEN_CODE_ENABLE_LSP=1 and QWEN_CODE_DISABLE_LSP=1 override both (disable wins); workspace-scoped values are ignored.
// ~/.qwen/settings.json (user scope)
{ "tools": { "lspEnabled": true } }Q: How do I know which language servers are running?
Start Qwen Code with LSP enabled (setting or flag) and debug mode on:
qwen --debugThen run /status for a short summary, /lsp for per-server status, or inspect the debug log:
# Default runtime directory
rg "LSP|Native LSP|<server-name>" ~/.qwen/debug/latest
# Or:
grep -E "LSP|Native LSP|<server-name>" ~/.qwen/debug/latest
# If QWEN_RUNTIME_DIR is configured
rg "LSP|Native LSP|<server-name>" "$QWEN_RUNTIME_DIR/debug/latest"LSP uses Qwen Code’s normal --debug mode; there is no separate LSP debug flag.
Q: Can I use multiple language servers for the same file type?
Yes, but only one will be used for each operation. The first server that returns results wins.
Q: Does LSP work in sandbox mode?
LSP servers run outside the sandbox to access your code. They’re subject to workspace trust controls.