Preview build — page text is a draft awaiting human review. Code badges come from real compiles. The flasher is real but not yet hardware-tested; the Playground is still a preview.
Get Started
MicroPython · Wi-Fi

Fix ESP32 MicroPython “OSError: Wifi Internal Error”

connect() was called while the radio was already connecting or still up after a soft reset. Activate once, check isconnected(), disconnect before reconnecting.

ESP32ESP32-S3ESP32-C3Updated 3 Nov 2026

Community draft — report a mistake

What you see

OutputOutput
MPY: soft reboot
MicroPython v1.24.1 on 2024-11-29; Generic ESP32 module with ESP32
Type "help()" for more information.
>>> %Run -c $EDITOR_CONTENT
Traceback (most recent call last):
  File "<stdin>", line 6, in <module>
OSError: Wifi Internal Error

“Wifi Internal Error” is the ESP32 Wi-Fi driver refusing a request that doesn’t fit its current state — usually a second connect() while it is already connected or still trying. A connect function that is safe to call any number of times:

import network, time

wlan = network.WLAN(network.STA_IF)
wlan.active(True)

def wifi(ssid, pwd, timeout=20):
    if wlan.isconnected():
        return True
    wlan.disconnect()
    wlan.connect(ssid, pwd)
    for _ in range(timeout * 2):
        if wlan.isconnected():
            return True
        time.sleep(0.5)
    return False

Quick fix — try in order

  1. 1

    Only connect if not already connected

    Wrap it: if not wlan.isconnected(): wlan.connect(ssid, pwd). After Ctrl-D (soft reboot) the ESP32 radio is often still connected from the last run.

  2. 2

    Call active(True) once, before connect()

    wlan = network.WLAN(network.STA_IF); wlan.active(True). Calling connect() on an inactive interface gives Wifi Not Started or this error.

  3. 3

    Disconnect before a new attempt

    In a reconnect loop, call wlan.disconnect() and wait a moment before connect() again. Don’t call connect() every loop while it is still trying.

  4. 4

    Reset the radio if it is stuck

    wlan.active(False); time.sleep(1); wlan.active(True) clears most stuck states without rebooting the board.

  5. 5

    Hard reset as a last resort

    machine.reset() or the EN button restarts the Wi-Fi driver completely.

Why it happens

Why does it only happen the second time I run the script?

Thonny’s Run does a soft reboot, which restarts Python but not the Wi-Fi driver. The first run left the station connected (or connecting), and the second connect() collides with it.

Both AP and STA active

Running an access point (AP_IF) and joining a router (STA_IF) at once works, but they must use the router’s channel. Turn the AP off if you don’t need it.

Brownout during connect

A weak USB cable or supply can reset the radio mid-connect. If you also see resets, check Brownout detector was triggered.

Board-specific notes

ESP32: Once connected, a DNS failure shows up as OSError: -202, not this error.

Pico W: Does not raise this message. Use wlan.status(): -3 wrong password, -2 network not found, -1 failed.

↑↓ to move · Enter to open