How to Debug Connection Issues with the Qwen Code IDE Integration Plugins

Connection failures occur when the VS Code extension’s internal HTTP MCP server cannot validate the one-time authentication token stored in the IDE lock file or when the required environment variables are missing from the process context.

The Qwen Code IDE integration relies on an internal HTTP MCP server launched within the VS Code extension to handle tool requests from companion web-views and CLI processes. When you debug connection issues with the IDE integration plugins, you are essentially verifying that the server started correctly, wrote its authentication credentials to the lock file, and exported the necessary environment variables for client discovery. This guide walks through the diagnostic checkpoints implemented in the QwenLM/qwen-code repository.

Verify the IDE Server Status via Output Logs

The extension streams diagnostic messages to a dedicated output channel named "Qwen Code Companion." Open this channel via View → Output → Qwen Code Companion to inspect the startup sequence.

When healthy, the log contains an entry specifying the listening port:

IDE server listening on http://127.0.0.1:50734
Writing IDE lock file to: /home/you/.qwen/ide/50734.lock

If the "listening" line is absent, the server failed to start. Review preceding error messages for EADDRINUSE (port conflict) or permission errors thrown during the ideServer.start routine in extension.ts.

Inspect the Authentication Lock File

The lock file acts as the single source of truth for port, workspace path, and session authentication. It is written by the writePortAndWorkspace function in [ide-server.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/ide-server.ts) to ~/.qwen/ide/<port>.lock.

Verify the file contents from a terminal:

cat ~/.qwen/ide/$(cat ~/.qwen/ide/*.lock | jq -r .port).lock

A valid lock file contains the following JSON structure:

{
  "port": 50734,
  "workspacePath": "/home/you/my-project",
  "ppid": 12345,
  "authToken": "c5f44cfa-2e3a-4a7b-b9aa-f6c1e4c8c123",
  "ideName": "VS Code"
}

If the file is missing, the writePortAndWorkspace routine never executed, indicating a crash during server initialization. If the file exists but is empty, verify that your umask allows the extension to apply its default chmod 600 permissions.

Validate the Required Environment Variables

The extension injects discovery variables into the VS Code process environment using context.environmentVariableCollection.replace as defined in [extension.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/extension.ts):

• QWEN_CODE_IDE_SERVER_PORT
• QWEN_CODE_IDE_WORKSPACE_PATH

Confirm these are set inside the integrated terminal:

echo $QWEN_CODE_IDE_SERVER_PORT
echo $QWEN_CODE_IDE_WORKSPACE_PATH

Both must return non-empty strings. If they are undefined, the IDEServer instance failed to start, and the companion tools cannot locate the HTTP endpoint.

Manually Test the MCP HTTP Endpoint

Test connectivity from a terminal outside VS Code to rule out environment inheritance issues. The server expects a valid Bearer token and a JSON-RPC initialize request that satisfies the isInitializeRequest check in [ide-server.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/ide-server.ts).

PORT=$(echo $QWEN_CODE_IDE_SERVER_PORT)
TOKEN=$(jq -r .authToken ~/.qwen/ide/$PORT.lock)

curl -i -X POST "http://127.0.0.1:$PORT/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{}}'

A healthy server returns HTTP 200 OK with a JSON-RPC response envelope. A 401 Unauthorized error indicates an authToken mismatch, while 403 Forbidden suggests a failed CORS or Host header validation.

Review CORS and Host Header Restrictions

The server enforces strict origin and host checks via middleware in [ide-server.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/ide-server.ts). It rejects any request carrying an Origin header (browser-based requests) and validates the Host header against an allowedHosts array:

const allowedHosts = [
  `localhost:${this.port}`,
  `127.0.0.1:${this.port}`,
  `host.docker.internal:${this.port}`,
];

If you are developing inside a Docker container or using a custom DNS alias, ensure the request Host matches one of these patterns. Override the header in your test command if necessary:

curl -H "Host: 127.0.0.1:$PORT" ...

Check VS Code Developer Tools for Traces

Open Help → Toggle Developer Tools and inspect the Console tab for messages prefixed with [WebViewProvider] or [IDE Server]. The IDEServer class logs trace events via the log callback passed to its constructor, and any uncaught exceptions from the Express middleware will surface here with full stack traces.

Resolve Common Connection Failures

Use the following symptom-based guide to pinpoint the root cause:

• "Failed to write IDE lock file" — The extension lacks write permissions for ~/.qwen/ide. Create the directory manually and ensure it is writable (chmod -R u+rw ~/.qwen).

• "Invalid auth token" (401) — The client is presenting a stale token or the lock file was regenerated. Delete all *.lock files in ~/.qwen/ide and reload the VS Code window to generate a fresh token.

• "Request denied by CORS policy" (403) — The request includes an Origin header, which the server interprets as a browser cross-origin request. Execute the client as a native Node.js script or explicitly set Origin: null.

• "Invalid Host header" (403) — The Host header does not match the allowedHosts whitelist. Use localhost, 127.0.0.1, or host.docker.internal as the target hostname.

• No "IDE server listening" log entry — The port is already in use or the Node process lacks binding privileges. Terminate any stray qwen-code processes and reload the extension.

Run the Automated Diagnostic Script

Execute the following bash script inside a VS Code terminal to validate the entire connection path automatically:

#!/usr/bin/env bash
set -euo pipefail

# 1️⃣ Verify env vars

echo "Port env var: $QWEN_CODE_IDE_SERVER_PORT"
echo "Workspace env var: $QWEN_CODE_IDE_WORKSPACE_PATH"

# 2️⃣ Load lock file

LOCK="$HOME/.qwen/ide/${QWEN_CODE_IDE_SERVER_PORT}.lock"
if [[ ! -f "$LOCK" ]]; then
  echo "❌ Lock file missing: $LOCK"
  exit 1
fi
TOKEN=$(jq -r .authToken "$LOCK")
echo "Auth token: $TOKEN"

# 3️⃣ Test HTTP endpoint

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Host: 127.0.0.1:$QWEN_CODE_IDE_SERVER_PORT" \
  -X POST "http://127.0.0.1:$QWEN_CODE_IDE_SERVER_PORT/mcp" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{}}'

A 200 response confirms the IDE server is fully operational; any other code maps to the failure scenarios above.

Reference the Core Source Files

The following files in QwenLM/qwen-code define the connection logic:

• [ide-server.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/ide-server.ts) — Implements the Express MCP server, writePortAndWorkspace, CORS middleware, and the allowedHosts validation.
• [extension.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/extension.ts) — VS Code activation entry point; instantiates IDEServer and registers environment variables.
• [detect-ide.js](https://github.com/QwenLM/qwen-code/blob/main/packages/qwen-code-core/src/ide/detect-ide.js) — Detects the hosting IDE for contextual logging.
• [constants/acpSchema.js](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/constants/acpSchema.js) — Defines error constants such as AUTH_REQUIRED.
• [webview/WebViewProvider.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/webview/WebViewProvider.ts) — Client-side request logic that consumes the IDE server.
• [diff-manager.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/diff-manager.ts) — Registers tools that require an active connection.

Summary

• The IDE integration requires the "Qwen Code Companion" output channel to show a successful "listening" log entry.
• Authentication depends on a valid lock file at ~/.qwen/ide/<port>.lock containing a matching authToken.
• Clients must use the QWEN_CODE_IDE_SERVER_PORT and QWEN_CODE_IDE_WORKSPACE_PATH environment variables to locate the server.
• Requests must include the correct Authorization: Bearer header and satisfy strict Host header validation against localhost, 127.0.0.1, or host.docker.internal.
• Delete stale lock files and reload the extension to resolve token mismatches or permission errors.

Frequently Asked Questions

Why does the server return 401 Unauthorized?

The Authorization header token does not match the authToken stored in the current lock file. This usually happens when the extension restarted and generated a new token, but a client process is still caching the old one. Delete the existing .lock files and reload VS Code to synchronize the tokens.

Can I use a custom hostname instead of localhost?

No. The allowedHosts array in ide-server.ts explicitly restricts valid hosts to localhost, 127.0.0.1, and host.docker.internal. Requests with any other Host header receive a 403 Forbidden response to prevent DNS rebinding attacks.

What should I do if no lock file appears after starting VS Code?

Check the Qwen Code Companion output channel for file system errors. The writePortAndWorkspace function may lack permissions to create ~/.qwen/ide. Ensure your user owns the directory and that a restrictive umask is not blocking the chmod 600 operation applied to the lock file.

How do I verify the MCP protocol is working correctly?

Send a JSON-RPC initialize request using the provided curl snippet. The server implements isInitializeRequest validation; a 200 OK response with a JSON-RPC envelope confirms that the transport, authentication, and protocol layers are all functional.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}