Skip to Content
User GuideFeaturesLSP (Language Server Protocol)

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:

LanguageLanguage ServerInstall Command
TypeScript/JavaScripttypescript-language-servernpm install -g typescript-language-server typescript
Pythonpylsppip install python-lsp-server
Gogoplsgo install golang.org/x/tools/gopls@latest
Rustrust-analyzerInstallation guide 
C/C++clangdInstall LLVM/clangd via your package manager
JavajdtlsInstall JDTLS and a JDK
C#roslyn-language-serverdotnet 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) or compile_flags.txt is 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-server global 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

OptionTypeDescription
commandstringCommand 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

OptionTypeDefaultDescription
argsstring[][]Command line arguments
transportstring"stdio"Transport type: stdio, tcp, or socket
envobject-Environment variables
initializationOptionsobject-LSP initialization options
settingsobject-Server settings via workspace/didChangeConfiguration
extensionToLanguageobject-Maps file extensions to language identifiers
workspaceFolderstring-Override workspace folder (must be within project root)
startupTimeoutnumber10000Startup timeout in milliseconds
shutdownTimeoutnumber5000Shutdown timeout in milliseconds
restartOnCrashbooleanfalseAuto-restart on crash
maxRestartsnumber3Maximum restart attempts
trustRequiredbooleantrueRequire 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 file

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 prepareCallHierarchy

Outgoing Calls

Find all functions called by the given function.

Operation: outgoingCalls Parameters: - callHierarchyItem: Item from prepareCallHierarchy

Diagnostics

File Diagnostics

Get diagnostic messages (errors, warnings) for a file.

Operation: diagnostics Parameters: - filePath: Path to the file

Workspace 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/warnings
  • refactor - Refactoring operations
  • refactor.extract - Extract to function/variable
  • refactor.inline - Inline function/variable
  • source - Source code actions
  • source.organizeImports - Organize imports
  • source.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.json servers are skipped. The repository cannot override this by setting trustRequired: false or 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

  1. Verify LSP is enabled: Use the tools.lspEnabled setting (user, system or system-defaults scope) or the --experimental-lsp flag; QWEN_CODE_ENABLE_LSP=1 / QWEN_CODE_DISABLE_LSP=1 override both (disable wins). Safe mode (--safe-mode, QWEN_CODE_SAFE_MODE=1) and --bare refuse LSP, and /lsp is not registered there
  2. Check if the server is installed: Run the command manually (e.g. clangd --version) to verify
  3. 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
  4. Check workspace trust: A workspace-declared server starts only in an explicitly trusted folder — enable security.folderTrust.enabled and 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.json changes, and the skip appears only in the --debug log as requires trusted workspace, skipping
  5. Check logs: Start Qwen Code with --debug, then search for LSP-related entries in the debug log (see Debugging section below)
  6. Check the process: Run ps aux | grep <server-name> to verify the server process is running

Slow Performance

  1. Large projects: Consider excluding node_modules and other large directories
  2. Server timeout: Increase startupTimeout in server configuration for slow servers

No Results

  1. Server not ready: The server may still be indexing. For C/C++ projects with clangd, ensure --background-index is in the args and a compile_commands.json (or compile_flags.txt) exists in the project root or a parent directory. Use --compile-commands-dir=<path> if it is in a build subdirectory
  2. File not saved: Save your file for the server to pick up changes
  3. Wrong language: Check if the correct server is running for your language
  4. 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 --debug

Debug 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 /status in 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 unavailable

For 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 initialize

For clangd startup failures, verify the server directly from the project root:

clangd --version clangd --check=/path/to/file.cpp --log=verbose

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

  1. Install language servers globally: This ensures they’re available in all projects
  2. Use project-specific settings: Configure server options per project when needed via .lsp.json
  3. Keep servers updated: Update your language servers regularly for best results
  4. 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 --debug

Then 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.

Last updated on