fix: improve proxy connection error detection and documentation

- Add proxy configuration detection utility
- Show warning when http.electronFetch is disabled with proxy settings
- Improve error messages to guide users to the solution
- Add comprehensive proxy configuration documentation
- Update README with link to proxy documentation

Fixes #6991

README.md

@@ -105,6 +105,7 @@ Make Roo Code work your way with:
 - [Custom Modes](https://docs.roocode.com/advanced-usage/custom-modes) for specialized tasks
 - [Local Models](https://docs.roocode.com/advanced-usage/local-models) for offline use
 - [Auto-Approval Settings](https://docs.roocode.com/advanced-usage/auto-approving-actions) for faster workflows
+- [Proxy Configuration](docs/PROXY_CONFIGURATION.md) for working with corporate proxies and VPNs
 
 ## Resources
 

docs/PROXY_CONFIGURATION.md

@@ -0,0 +1,108 @@
+# Proxy Configuration Guide
+
+## Issue: Connection Errors with Proxy Settings
+
+If you're experiencing "Connection error" messages when using Roo Code with a proxy (SOCKS5, HTTP proxy, or PAC file), this guide will help you resolve the issue.
+
+## Problem
+
+When VSCode is configured to use a proxy (via environment variables, settings, or command-line arguments), but the `http.electronFetch` setting is disabled (which is the default), the extension may fail to connect to API endpoints. This particularly affects:
+
+- OpenAI API connections
+- OpenAI-compatible API providers
+- Other providers that use the native `fetch` API
+
+## Symptoms
+
+- Generic "Connection error" messages when trying to use the extension
+- Models populate correctly but chat completions fail
+- Network Logger shows requests but they don't reach the server
+- The same configuration works in other extensions (like Cline)
+
+## Solution
+
+### Option 1: Enable Electron Fetch (Recommended)
+
+1. Open VSCode Settings (`Cmd/Ctrl + ,`)
+2. Search for `http.electronFetch`
+3. Check the box to enable the setting
+4. Restart VSCode
+5. Try using Roo Code again
+
+### Option 2: Use Command Line
+
+Add this to your VSCode settings.json:
+
+```json
+{
+	"http.electronFetch": true
+}
+```
+
+### Option 3: Configure VSCode Launch
+
+If you're launching VSCode with a PAC file, ensure both settings are configured:
+
+```bash
+code --proxy-pac-url=http://localhost:8000/proxy.pac
+```
+
+And enable `http.electronFetch` in settings.
+
+## Why This Happens
+
+VSCode has two different implementations for making HTTP requests:
+
+1. **Node.js fetch** (default): Doesn't fully support all proxy configurations
+2. **Electron fetch**: Better proxy support but disabled by default
+
+When `http.electronFetch` is `false` (default), extensions using the native fetch API may fail to route requests through your proxy correctly.
+
+## Automatic Detection
+
+Roo Code now automatically detects this configuration issue and will:
+
+1. Show a warning notification when proxy settings are detected but `http.electronFetch` is disabled
+2. Provide helpful error messages when connection errors occur
+3. Suggest the appropriate fix based on your configuration
+
+## Supported Proxy Types
+
+With `http.electronFetch` enabled, the following proxy configurations are supported:
+
+- HTTP/HTTPS proxies (via `http.proxy` setting or environment variables)
+- SOCKS5 proxies
+- PAC (Proxy Auto-Configuration) files
+- Environment variables: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`
+
+## Troubleshooting
+
+If you're still experiencing issues after enabling `http.electronFetch`:
+
+1. **Verify proxy settings**: Ensure your proxy configuration is correct
+2. **Check firewall rules**: Make sure VSCode is allowed through your firewall
+3. **Test connectivity**: Try accessing the API endpoint directly via curl or browser
+4. **Check API credentials**: Ensure your API keys are valid and have the necessary permissions
+5. **Review logs**: Check the Roo Code output channel for detailed error messages
+
+## Alternative Solutions
+
+If enabling `http.electronFetch` doesn't resolve your issue:
+
+1. **Temporarily disable proxy**: If the proxy isn't required for the API endpoint
+2. **Use a different provider**: Some providers may work better with your proxy setup
+3. **Configure proxy exceptions**: Add API endpoints to your proxy bypass list
+
+## Related Issues
+
+- [VSCode Issue #12588](https://github.com/microsoft/vscode/issues/12588) - Original discussion about proxy support
+- [Roo Code Issue #6991](https://github.com/RooCodeInc/Roo-Code/issues/6991) - Specific issue about connection errors with proxies
+
+## Need Help?
+
+If you're still experiencing issues, please:
+
+1. Open an issue on [GitHub](https://github.com/RooCodeInc/Roo-Code/issues)
+2. Include your proxy configuration (without sensitive information)
+3. Provide the error messages from the Roo Code output channel
+4. Mention whether `http.electronFetch` is enabled

src/api/providers/utils/proxy-detection.ts

@@ -0,0 +1,138 @@
+import * as vscode from "vscode"
+
+/**
+ * Detects if the user has proxy settings configured but http.electronFetch is disabled.
+ * This combination can cause connection errors with certain API providers.
+ */
+export function detectProxyConfigurationIssue(): {
+	hasProxyConfig: boolean
+	electronFetchEnabled: boolean
+	hasIssue: boolean
+	proxySettings: string[]
+} {
+	const config = vscode.workspace.getConfiguration()
+
+	// Check for proxy-related settings
+	const httpProxy = config.get<string>("http.proxy")
+	const httpsProxy = process.env.HTTPS_PROXY || process.env.https_proxy
+	const httpProxyEnv = process.env.HTTP_PROXY || process.env.http_proxy
+	const allProxy = process.env.ALL_PROXY || process.env.all_proxy
+
+	// Check if electronFetch is enabled (default is false in VSCode)
+	const electronFetchEnabled = config.get<boolean>("http.electronFetch", false)
+
+	// Collect all proxy settings found
+	const proxySettings: string[] = []
+	if (httpProxy) proxySettings.push(`VSCode http.proxy: ${httpProxy}`)
+	if (httpsProxy) proxySettings.push(`HTTPS_PROXY: ${httpsProxy}`)
+	if (httpProxyEnv) proxySettings.push(`HTTP_PROXY: ${httpProxyEnv}`)
+	if (allProxy) proxySettings.push(`ALL_PROXY: ${allProxy}`)
+
+	// Check if running with proxy PAC file
+	const args = process.argv.join(" ")
+	const hasPacFile = args.includes("--proxy-pac-url")
+	if (hasPacFile) {
+		const pacMatch = args.match(/--proxy-pac-url[= ]([^ ]+)/)
+		if (pacMatch) {
+			proxySettings.push(`PAC file: ${pacMatch[1]}`)
+		}
+	}
+
+	const hasProxyConfig = proxySettings.length > 0
+	const hasIssue = hasProxyConfig && !electronFetchEnabled
+
+	return {
+		hasProxyConfig,
+		electronFetchEnabled,
+		hasIssue,
+		proxySettings,
+	}
+}
+
+/**
+ * Formats a helpful error message when proxy configuration issues are detected
+ */
+export function formatProxyErrorMessage(
+	error: any,
+	proxyInfo?: ReturnType<typeof detectProxyConfigurationIssue>,
+): string {
+	const baseError = error?.message || "Connection error"
+
+	if (!proxyInfo) {
+		proxyInfo = detectProxyConfigurationIssue()
+	}
+
+	if (proxyInfo.hasIssue) {
+		return `${baseError}
+
+⚠️ **Proxy Configuration Issue Detected**
+
+You have proxy settings configured but \`http.electronFetch\` is disabled (default). This can cause connection errors with API providers.
+
+**Detected proxy settings:**
+${proxyInfo.proxySettings.map((s) => `• ${s}`).join("\n")}
+
+**Solution:**
+1. Open VSCode Settings (Cmd/Ctrl + ,)
+2. Search for "http.electronFetch"
+3. Enable the setting (check the box)
+4. Restart VSCode and try again
+
+**Alternative solutions:**
+• Use a different API provider that works with your proxy setup
+• Configure the extension to use axios-based providers when available
+• Temporarily disable proxy settings if not needed
+
+For more information, see: https://github.com/microsoft/vscode/issues/12588`
+	}
+
+	// Check for other common connection errors
+	if (baseError.includes("ECONNREFUSED")) {
+		return `${baseError}
+
+The connection was refused. Please check:
+• Is the API endpoint URL correct?
+• Is the service running and accessible?
+• Are there any firewall or network restrictions?`
+	}
+
+	if (baseError.includes("ETIMEDOUT") || baseError.includes("ESOCKETTIMEDOUT")) {
+		return `${baseError}
+
+The connection timed out. Please check:
+• Is the API endpoint accessible from your network?
+• Are you behind a corporate firewall or VPN?
+• Is the service experiencing high load?`
+	}
+
+	if (baseError.includes("ENOTFOUND")) {
+		return `${baseError}
+
+The hostname could not be resolved. Please check:
+• Is the API endpoint URL spelled correctly?
+• Do you have internet connectivity?
+• Are DNS settings configured correctly?`
+	}
+
+	return baseError
+}
+
+/**
+ * Shows a warning notification if proxy configuration issues are detected
+ */
+export async function showProxyConfigurationWarning(): Promise<void> {
+	const proxyInfo = detectProxyConfigurationIssue()
+
+	if (proxyInfo.hasIssue) {
+		const message = "Proxy detected but http.electronFetch is disabled. This may cause connection errors."
+		const action = await vscode.window.showWarningMessage(message, "Enable electronFetch", "Learn More", "Dismiss")
+
+		if (action === "Enable electronFetch") {
+			// Open settings and navigate to the http.electronFetch setting
+			await vscode.commands.executeCommand("workbench.action.openSettings", "http.electronFetch")
+		} else if (action === "Learn More") {
+			// Open the GitHub issue for more information
+			await vscode.env.openExternal(vscode.Uri.parse("https://github.com/microsoft/vscode/issues/12588"))
+		}
+	}
+}

src/core/task/Task.ts

@@ -9,6 +9,7 @@ import delay from "delay"
 import pWaitFor from "p-wait-for"
 import { serializeError } from "serialize-error"
 
+import { detectProxyConfigurationIssue, formatProxyErrorMessage } from "../../api/providers/utils/proxy-detection"
 import {
 	type TaskLike,
 	type TaskEvents,
@@ -2221,10 +2222,7 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 
 				return
 			} else {
-				const { response } = await this.ask(
-					"api_req_failed",
-					error.message ?? JSON.stringify(serializeError(error), null, 2),
-				)
+				const { response } = await this.ask("api_req_failed", formatProxyErrorMessage(error))
 
 				if (response !== "yesButtonClicked") {
 					// This will never happen since if noButtonClicked, we will

src/extension.ts

@@ -24,6 +24,7 @@ import { ContextProxy } from "./core/config/ContextProxy"
 import { ClineProvider } from "./core/webview/ClineProvider"
 import { DIFF_VIEW_URI_SCHEME } from "./integrations/editor/DiffViewProvider"
 import { TerminalRegistry } from "./integrations/terminal/TerminalRegistry"
+import { showProxyConfigurationWarning } from "./api/providers/utils/proxy-detection"
 import { McpServerManager } from "./services/mcp/McpServerManager"
 import { CodeIndexManager } from "./services/code-index/manager"
 import { MdmService } from "./services/mdm/MdmService"
@@ -81,6 +82,9 @@ export async function activate(context: vscode.ExtensionContext) {
 	// Initialize i18n for internationalization support.
 	initializeI18n(context.globalState.get("language") ?? formatLanguage(vscode.env.language))
 
+	// Check for proxy configuration issues and show warning if needed
+	await showProxyConfigurationWarning()
+
 	// Initialize terminal shell execution handlers.
 	TerminalRegistry.initialize()