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

> Quickly debug Qwen Code IDE integration connection issues. Learn to validate auth tokens and set environment variables for seamless integration.

- Repository: [Qwen/qwen-code](https://github.com/qwenlm/qwen-code)
- Tags: how-to-guide
- Published: 2026-02-19

---

**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:

```text
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`](https://github.com/QwenLM/qwen-code/blob/main/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/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:

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

```

A valid lock file contains the following JSON structure:

```json
{
  "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/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:

```bash
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/ide-server.ts)](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/ide-server.ts)**.

```bash
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/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:

```typescript
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:

```bash
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:

```bash
#!/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/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/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/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/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/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/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`](https://github.com/QwenLM/qwen-code/blob/main/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.