Troubleshooting

Proxy can't connect to WinCC

[WARN] Cannot connect to localhost:9222

Verify the debug endpoint

Test the connection step by step to isolate any issues:

1. On the WinCC machine, test localhost:

http://localhost:9222/json

You should see a JSON response listing the available debug targets. If the page doesn't load, the debugger is not enabled or the runtime hasn't been restarted after enabling it.

2. On the WinCC machine, test via IP address:

http://<WINCC_IP>:9222/json

If this fails but localhost works, the port forwarding is not set up correctly. See Remote Debugging to generate and run the setup scripts.

3. From your own PC, test via IP address:

http://<WINCC_IP>:9222/json

If this fails but the previous step works on the WinCC machine, the port forwarding or firewall is not configured correctly. Run wincc-debug-setup-<ip>.bat as Administrator on the WinCC machine — see Remote Debugging for details.

Check that WinCC is running

Make sure the WinCC Unified runtime is active with the script debugger enabled in SIMATIC Runtime Manager. See WinCC Setup for the full setup steps.

Check that a browser is open

The WinCC runtime must be open in a browser for debug endpoints to exist. Without an active browser session, port 9222 will not have any targets - even if the debugger is enabled.

Check the port

Verify that port 9222 is listening:

netstat -an | findstr 9222

You should see a line with LISTENING.

VS Code won't connect

Proxy not running

Make sure the proxy is active and has shown the [READY] message before starting the debugger in VS Code.

Wrong port in launch.json

Check that the ports in launch.json match the proxy ports:

If you use custom ports with run, update launch.json accordingly.

Timeout

If VS Code gives a timeout error, increase the timeout value in launch.json:

"timeout": 60000

VS Code doesn't reconnect after screen reload

restart setting

Make sure "restart": true is present in your launch.json configuration. Without it, VS Code won't automatically reconnect.

Check the proxy logs

Start the proxy with verbose logging to see what's happening:

./wincc-unified-debug-proxy.exe run -v

You should see [CHANGE] messages when a target changes, followed by [STOP] and a new [CONN].

Port 9222 not reachable via IP (only localhost works)

If you can access http://localhost:9222/json on the WinCC machine but not via its IP address (e.g. http://10.0.0.65:9222/json), the portproxy rule is likely broken.

The fix is to run the restart script as Administrator on the WinCC machine:

wincc-debug-restart-<ip>.bat

If you don't have the scripts yet, generate them first:

./wincc-unified-debug-proxy.exe generate -a <WINCC_IP>

Verify the rule is active:

netsh interface portproxy show all

Also make sure the IP Helper service is running, as portproxy depends on it:

sc query iphlpsvc

If it's not running:

sc start iphlpsvc
sc config iphlpsvc start=auto

Quick isolation test

If you're unsure whether it's a firewall or portproxy issue, temporarily disable the firewall to isolate the cause:

netsh advfirewall set allprofiles state off

Test http://<WINCC_IP>:9222/json in the browser. Then re-enable the firewall immediately:

netsh advfirewall set allprofiles state on

Script paths are too long in VS Code

By default, WinCC script paths are automatically shortened so you can see the relevant part (screen and faceplate name) when browsing loaded scripts via Debug: Open Loaded Script... in the command palette. If you're still seeing full paths, check that path shortening is active (it's on by default - only disabled with --long-paths).

Example:

# Original (long)
/screen_modules/Screen_Content/HMI_RT_1::HMI_Screen/faceplate_modules/FaceplateName/Events.js

# Shortened (default)
HMI_Screen/FaceplateName/Events.js

If you want to see full paths, use:

./wincc-unified-debug-proxy.exe run --long-paths

Multiple targets found

[WARN] Multiple alive Dynamics targets found (3), selecting highest VCS number!

The proxy automatically selects the most recent active session, but you should investigate the cause:

Multiple browsers or tabs open

Make sure only one browser tab with the WinCC runtime is open. Each tab creates its own debug session. Close any extra tabs and the warning should disappear.

Stale debug endpoints

If only one tab is open, WinCC may have leftover debug endpoints from a previous session that didn't clean up properly. Restart the WinCC runtime to clear them.