# VS Code Port Forwarding Failed
You're developing with a remote server or container, and port forwarding should expose your app locally, but it fails. The forwarded URL shows "Connection refused", or the port never becomes available. Port forwarding is essential for remote development, and when it breaks, you can't preview your work locally.
Introduction
This article covers troubleshooting steps and solutions for VS Code Port Forwarding Failed - Complete Troubleshooting Guide. The error typically occurs in production environments and can cause service disruptions if not addressed promptly.
Symptoms
Common error messages include:
# On remote machine (SSH or container terminal)
netstat -tlnp | grep 3000
# or
lsof -i :3000
# or
ss -tlnp | grep 3000```bash # Example: Node app node app.js
# Example: Python app python manage.py runserver 0.0.0.0:8000 ```
```bash # WRONG - won't forward python manage.py runserver 127.0.0.1:8000
# RIGHT - can forward python manage.py runserver 0.0.0.0:8000 ```
Common Causes
- Configuration misconfiguration
- Missing or incorrect credentials
- Network connectivity issues
- Version compatibility problems
- Resource exhaustion or limits
- Permission or access denied
Step-by-Step Fix
- 1.Check logs for specific error messages
- 2.Verify configuration settings
- 3.Test network connectivity
- 4.Review recent changes
- 5.Apply corrective action
- 6.Verify the fix
Understanding Port Forwarding
VS Code port forwarding creates a tunnel between:
- 1.A port on the remote machine (where your app runs)
- 2.A port on your local machine (where you access it)
This lets you view remote applications in your local browser.
Step 1: Check If App Is Running on Remote
Before forwarding, your app must listen on the remote:
Check if app is running:
``bash
# On remote machine (SSH or container terminal)
netstat -tlnp | grep 3000
# or
lsof -i :3000
# or
ss -tlnp | grep 3000
Start your app: ```bash # Example: Node app node app.js
# Example: Python app python manage.py runserver 0.0.0.0:8000 ```
Critical: Bind to 0.0.0.0, not localhost Apps bound to localhost (127.0.0.1) only aren't accessible for forwarding: ```bash # WRONG - won't forward python manage.py runserver 127.0.0.1:8000
# RIGHT - can forward python manage.py runserver 0.0.0.0:8000 ```
Step 2: Manually Forward Port
VS Code can auto-detect ports, but manual forwarding is more reliable:
- 1.Manual forward:
- 2.Ports panel (View → Ports or "Ports: Focus on Ports View")
- 3."Forward a Port" button
- 4.Enter the remote port number (e.g., 3000)
- 5.Local URL appears in the list
Command palette:
Ctrl+Shift+P → "Ports: Forward Port" → Enter port
Step 3: Fix "Connection Refused" Errors
Local forwarded URL shows connection refused:
Verify remote app:
``bash
# On remote, test with curl
curl http://localhost:3000
curl http://127.0.0.1:3000
If curl fails, app isn't running or listening.
Check binding:
``bash
# App must bind to 0.0.0.0 or be accessible from localhost
netstat -tlnp | grep 3000
Output should show 0.0.0.0:3000 or *:3000, not just 127.0.0.1:3000.
Step 4: Handle Port Conflicts
Local port might be in use:
Check local port:
``bash
# On your local machine
netstat -tlnp | grep 3000
lsof -i :3000
- 1.Use different local port:
- 2.In Ports panel:
- 3.Right-click forwarded port
- 4."Change Local Port"
- 5.Enter a different number (e.g., 3001)
Configure auto-forward settings:
``json
{
"remote.autoForwardPorts": true,
"remote.autoForwardPortSource": "process" // Detect from running processes
}
Step 5: Fix SSH Remote Forwarding
SSH remote port forwarding has specific requirements:
Check SSH config:
``
Host myserver
HostName 192.168.1.100
User myuser
LocalForward 3000 127.0.0.1:3000
VS Code SSH settings:
``json
{
"remote.SSH.remoteServerListenOnLocal": true,
"remote.SSH.enableDynamicForwarding": true
}
Restart SSH connection: Close remote window, reconnect.
Step 6: Handle Container Port Forwarding
Dev Containers require port configuration:
Configure in devcontainer.json:
``json
{
"forwardPorts": [3000, 8000, 8080],
"portsAttributes": {
"3000": {
"label": "Web App",
"onAutoForward": "notify",
"protocol": "http"
}
}
}
Docker run port mapping:
If using custom Docker setup:
``bash
docker run -p 3000:3000 your-image
Step 7: Fix Firewall and Network Issues
Firewalls block forwarded connections:
Windows:
``powershell
# Allow port through firewall
netsh advfirewall firewall add rule name="VS Code Port 3000" dir=in action=allow protocol=TCP localport=3000
Linux:
``bash
# Check firewall
sudo ufw status
sudo ufw allow 3000/tcp
macOS: Check Security & Privacy → Firewall → Allow VS Code.
Step 8: Handle Private Port Forwarding
Private ports (below 1024) need special handling:
Use higher ports: Instead of port 80, use 8080. Instead of 443, use 8443.
Or configure SSH:
``
Host myserver
PermitLocalOpen yes
Step 9: Check Port Forwarding Status
VS Code shows port status in the Ports panel:
Status indicators: - Green circle: Forwarded successfully - Gray/hollow: Not forwarded - Red: Error
View port details: Click port entry → See "Local Address" and "Running Process"
Step 10: Debug with Logs
Enable port forwarding logging:
{
"remote.SSH.logLevel": "trace"
}Output panel → "Remote - SSH" → Look for forwarding messages.
Verification
Test port forwarding works:
- 1.Start app on remote (bound to 0.0.0.0)
- 2.Forward port in Ports panel
- 3.Open local URL in browser (http://localhost:3000)
- 4.Should see your remote app
- 5.Stop app → forwarded URL should show connection refused
- 6.Restart app → URL should work again
Verification
| Problem | Cause | Solution |
|---|---|---|
| Connection refused | App not running | Start app on remote |
| Connection refused | Wrong binding | Bind to 0.0.0.0 not 127.0.0.1 |
| Port won't forward | Port conflict | Change local port |
| SSH forwarding fails | SSH config | Check LocalForward setting |
| Container forwarding fails | Missing config | Add forwardPorts to devcontainer |
| Firewall blocks | Port blocked | Allow through firewall |
Port forwarding issues usually stem from the app not running or binding incorrectly. Verify app is listening on 0.0.0.0 before troubleshooting VS Code settings.
Related Articles
- [VS Code Auto Save Not Working](fix-vscode-auto-save)
- [VS Code Bracket Colorization Not Working](fix-vscode-bracket-colorization)
- [Fix Fix Vscode Copilot Not Working Issue in VS Code](fix-vscode-copilot-not-working)
- [VS Code Debugger Not Attaching - Complete Troubleshooting Guide](fix-vscode-debugger-not-attaching)
- [Fix VS Code Debugging Not Stopping at Breakpoints: Breakpoints Ignored](fix-vscode-debugging-breakpoints-not-working)
<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "TechArticle", "headline": "VS Code Port Forwarding Failed - Complete Troubleshooting Guide", "description": "Resolve VS Code port forwarding problems. Fix connection refused errors, port conflicts, and remote development forwarding issues.", "url": "https://www.fixwikihub.com/fix-vscode-port-forwarding-failed", "publisher": { "@type": "Organization", "name": "FixWikiHub", "url": "https://www.fixwikihub.com" }, "author": { "@type": "Person", "name": "FixWikiHub Editorial Team" }, "datePublished": "2025-11-26T10:23:45.652Z", "dateModified": "2025-11-26T10:23:45.652Z" } </script>