Fix Windsurf Connection Issues: 6 Tested Solutions

Overview

Windsurf connection issues range from the AI autocomplete silently stopping to Cascade returning blank panels and internal errors. The most reported error — couldn't create connection to server with ECONNREFUSED 127.0.0.1:<port> — has appeared across GitHub issues since March 2025 and continues to affect users on all platforms.

This article covers six tested fixes targeting the most common root causes: backend outages, corrupted local caches, proxy and firewall blocks, macOS permission gaps, extension conflicts, and stale binaries. Work through them in order.

What Causes Windsurf Connection Errors

Connection failures in Windsurf fall into two categories: the local language server can’t start, or the editor can’t reach Codeium’s backend.

Local server failures produce this error loop in the output panel:

windsurf client: couldn't create connection to server
Error: connect ECONNREFUSED 127.0.0.1:43973
Restarting server failed

This typically happens after an update when the Codeium binary doesn’t match the expected VS Code base version, or when the Cascade cache becomes corrupted.

Backend connectivity failures surface as:

Error: request failed. Check your configuration.
Unknown: an internal error occurred
Unknown: Model provider is currently unavailable

Root causes include corporate firewalls blocking required domains, VPNs routing traffic through restrictive exit nodes, SSL-inspecting proxies breaking certificate verification, or simply a Codeium backend outage. On macOS, a dismissed Local Network permission prompt causes an Undefined error: 0 that blocks all connections silently.

Solution 1: Check Service Status and Account

Before touching any configuration, rule out the two most common causes: a backend outage and an expired subscription.

An exhausted free-tier credit balance is the single most common reason AI features stop responding without an obvious error. The UI doesn’t always surface this clearly.

Solution 2: Clear the Cascade Cache and Restart

Corrupted cache data causes the local Codeium server to fail on startup, producing the ECONNREFUSED loop. Clearing it forces a fresh initialization.

Delete the Cascade cache directory for your platform:

macOS / Linux:

rm -rf ~/.codeium/windsurf/cascade/

Windows (PowerShell):

Remove-Item -Recurse -Force "$env:USERPROFILE\.codeium\windsurf\cascade"

Restart Windsurf completely — not just reload the window, but quit and relaunch. Watch the Output panel (View → Output → select “Windsurf”) for connection success messages.

If the error persists, also delete the full Codeium config directory and let Windsurf rebuild it:

rm -rf ~/.codeium/

Solution 3: Configure Proxy and Firewall Rules

Corporate networks are the primary cause of connection failures for enterprise users. Windsurf needs outbound HTTPS access to several domains, plus WebSocket upgrade support.

Whitelist these domains in your firewall or proxy:

Configure proxy settings in Windsurf by opening the Command Palette (Ctrl + Shift + P on Windows/Linux, ⌘ + Shift + P on macOS) and selecting “Open User Settings (JSON)”:

{
  "http.proxy": "http://proxy.company.com:8080",
  "http.proxyStrictSSL": false
}

Set http.proxyStrictSSL to false only if your corporate proxy performs SSL inspection (MITM). This is common in enterprise environments where the proxy re-signs certificates with a corporate root CA.

Solution 4: Fix macOS Local Network Permission

On macOS, Windsurf requires Local Network access to communicate between its processes. If you dismissed the permission prompt on first launch, all connections fail silently with Undefined error: 0.

If Windsurf doesn’t appear in the Local Network list, you need to uninstall and reinstall the application to re-trigger the permission prompt. macOS doesn’t provide another way to surface a dismissed dialog.

Solution 5: Disable Conflicting Extensions

Extensions imported from VS Code — particularly other AI completion tools — can conflict with Windsurf’s built-in AI layer. GitHub Copilot and Tabnine are the most common offenders.

Open the Extensions panel (⌘ + Shift + X) and disable:

• GitHub Copilot / Copilot Chat
• Tabnine
• Amazon CodeWhisperer / Amazon Q
• Any other inline completion extension

Reload the window after disabling. Conflicting extensions cause symptoms ranging from doubled suggestions to complete autocomplete failure, and can interfere with the Codeium language server startup.

Solution 6: Reinstall the Codeium Binary

After major Windsurf updates, the Codeium server binary can become mismatched with the editor’s expected version. This is especially common on macOS Apple Silicon (M1/M2/M3) and produces persistent ECONNREFUSED errors that survive cache clearing.

Full clean reinstall:

# Remove all Windsurf and Codeium data
rm -rf ~/.windsurf/
rm -rf ~/.codeium/
rm -rf ~/.vscode/extensions/codeium.codeium-*/

Then reinstall Windsurf from windsurf.com. The fresh install downloads a matching binary and re-initializes all configuration.

$ rm -rf ~/.windsurf/ ~/.codeium/
Removing cached data...
$ ls ~/.codeium 2>&1
ls: cannot access '/home/user/.codeium': No such file or directory
✓ Clean state confirmed

Viewing Logs for Diagnosis

When none of the above solutions work, collect diagnostic logs before filing a bug report.

Windsurf output logs: Open the Command Palette → “Developer: Show Logs” → select “Windsurf” from the dropdown. Alternatively: View → Output → “Windsurf”.

Extension Host logs: View → Output → select “Extension Host”. Look for ECONNREFUSED, timeout errors, or binary version mismatches.

Developer Console: Help → Toggle Developer Tools → Console tab. This shows raw HTTP responses including status codes (429, 503, 504) that the Windsurf UI may suppress.

Copy the relevant error output when filing issues at github.com/Exafunction/codeium/issues.

Still Not Working?

If you’ve worked through all six solutions:

• File a bug report at github.com/Exafunction/codeium/issues with your OS, Windsurf version, and log output
• Check the official troubleshooting docs at docs.windsurf.com/troubleshooting
• Switch models temporarily — if Cascade returns “internal error” with one model provider (e.g., Claude), try switching to a different model in Cascade settings as a workaround
• Reduce context scope — instead of asking Cascade to work on an entire project, scope requests to a single file. Large contexts cause timeouts on the backend

FAQ