Get connected. Keep the working setup.

Check the cable and COM port

Use a data-capable USB cable. Confirm your board appears in Windows Device Manager or as a serial device on macOS/Linux, then choose the board's REPL port in Studio. Different CDC interfaces may appear as separate ports.

Avoid two programs owning one port

Close another serial terminal or flasher using the same COM port. If a tool has locked USB, close that tool before retrying. Do not delete boot.py or the debugger to solve a routine port-busy error.

Prove the REPL works before debugging

Open MicroPython: Open Device Shell. At the >>> prompt run print(1 + 1); expected result is 2. Only then test upload or debugging.

Check current board Wi-Fi and IP in USB REPL

These commands read status and do not write to the board's filesystem:

import network
sta = network.WLAN(network.STA_IF)
print("Connected:", sta.isconnected())
print("IP:", sta.ifconfig()[0])

If Wi-Fi is disconnected, follow your board's own Wi-Fi setup; don't assume an old IP address is still valid.

Confirm WebREPL is enabled on the board

Use Studio's Wi-Fi Manager or the board's existing configuration. In firmware that supports it, import webrepl makes the module available; it does not by itself start the server. An appropriate webrepl.start(...) call may be needed if no listener is running. Avoid restarting a healthy listener or overwriting user boot.py.

Test the TCP port from the computer

On Windows PowerShell, replace the example with the IP printed by the board:

Test-NetConnection <BOARD_IP> -Port 8266

On Linux/macOS with netcat installed:

nc -vz <BOARD_IP> 8266

Successful TCP connection: the service is reachable, but a correct WebREPL password is still needed. Failed TCP connection: investigate stale IP, board Wi-Fi state, routed network connectivity, access-point client isolation or whether a listener is running.

Check the PC and board networks

Compare the PC's current IP with the board's. Being on different subnets does not automatically prevent access—routing may exist—but they need a working network path. Joining the same reachable local network can simplify the first test. A failed ping alone does not prove WebREPL is stopped; TCP port 8266 is the relevant test.

Verify firmware identity

Stock MicroPython firmware does not include MicroPython Studio's live debugger transport. Check the exact board, firmware image and hardware acceptance status. A GitHub Actions green build is not proof of a working binary on your board.

Keep debugger and REPL channels separate

Connect Studio's normal device port to the REPL and use the additional transport required for the debugger. On Pico W's stable dual-CDC image they are different COM ports. On ESP32-S3 preview you may need two cables.

Run one small breakpoint test

Use a simple script with a known source line, then test Start Debug → Connect, pause, variables, Continue and disconnect. Only after this passes test RTA On/Off and long-running asynchronous programs.