An Error Occurred — Improv Wi-Fi Serial Not Detected | Fix

You’ll often hit this right after “Prepare for first use.” The flash step can complete, then the next screen fails because the board never starts the freshly written firmware, or the USB serial link drops at the wrong moment. The good news is that most cases come down to reset timing, boot mode, or a flaky USB path. Then try again.

The steps below are ordered so you can stop as soon as it works. Start with the quick checklist, then move into boot mode fixes and Wi-Fi fallback options.

Fix An Error Occurred — Improv Wi-Fi Serial Not Detected Fast

Think of this as two checks. Your computer must hold a steady serial connection, and your board must reboot into the app so it can speak Improv. When either side slips, the installer can’t find the Improv service and throws the same message.

Quick Checklist

1. Power cycle the board — Unplug USB, wait ten seconds, plug back in, then reconnect in the installer.
2. Press Reset after flashing — If your board has Reset, tap it once when the flash completes.
3. Release Boot and retry — If you held Boot to flash, let it go, reset, then run Wi-Fi setup again.
4. Use a known data cable — Swap in a cable you’ve used for flashing or file transfer, not one that only charges.
5. Close other serial tools — Quit serial monitors and terminals so the browser can claim the port.
6. Try Chrome or Edge — Web Serial works best in Chromium browsers; reload the page and reconnect.

If the Wi-Fi dialog appears after one of these, you’re done. If it still fails, the next sections help you narrow it down without guessing.

What The Message Means In Plain Terms

Improv Wi-Fi is a small, open handshake that sends Wi-Fi credentials to a device over a serial link. The browser is the client. Your firmware must include an Improv service that replies on that port.

When you see this error, the browser asked the device for its Improv state and got no valid reply. That does not always mean the flash failed. It can also mean the device stayed in download mode, the port is wrong, or the serial connection got grabbed by another app.

What You See	Likely Cause	Next Step
Flash completes, Wi-Fi screen never opens	Board did not reboot into the app	Reset or power cycle, then retry Wi-Fi setup
No logs appear in the browser	Wrong port or driver issue	Pick the correct port and check USB drivers
Only bootloader text shows	Boot pin held low	Release Boot, then reset again
Hotspot appears after a minute	Wi-Fi join failed	Use the hotspot portal to enter Wi-Fi

Once you understand the flow, troubleshooting gets calmer. You’re not chasing a “mystery error.” You’re just restoring a live serial conversation long enough to pass Wi-Fi details.

USB And Driver Problems That Break The Serial Handshake

A weak USB path can pass a flash step yet fail at Improv. Flashing uses a bootloader with retries. Improv is a live back-and-forth chat. If the port drops for a split second, the browser may give up.

On Windows, confirm the board shows up as a COM port in Device Manager. On macOS and Linux, you should see a tty device appear when you plug in. If the port never appears, install the driver for the USB-serial chip on your board, then reboot and try again.

Cable, Port, And Power

• Use a rear USB port — Desktop rear ports often hold steadier power than front hubs.
• Avoid long, thin cables — Shorter cables tend to hold the signal better.
• Watch for resets — If the board reboots the moment Wi-Fi starts, try a different port or a powered hub.

Common USB-Serial Chips

Many boards use CP2102, CH340, or FTDI USB-serial chips. If your OS can’t load the driver, the port can be missing, unstable, or mislabeled. If the port name changes each time you plug in, treat that as a clue.

• Restart the computer — A stuck driver session can keep the port busy even after you close the tab.
• Confirm the port by unplugging — Unplug the board and note which port vanishes, then plug back in and pick that one.
• Stop other apps from holding the port — Close IDEs and terminals that might auto-connect.

If you can’t get stable logs in the browser, fix that first. Improv can’t run if the browser can’t hold the port.

Boot Mode And Reset Timing After Flashing

This is the most common pattern. You hold Boot to enter download mode, the flash succeeds, then the board never exits that mode. Since the Improv service runs inside the application firmware, it will not appear until the board boots the app.

Fast Exit Steps

1. Let the Boot pin go — Release Boot before you reset so the chip can boot normally.
2. Press Reset once — Tap Reset right after flashing, then reconnect in the installer.
3. Power cycle fully — Unplug USB for ten seconds, then plug in again for a cold boot.
4. Check IO0 wiring — On many boards IO0 controls download mode; it must not be held low at boot.

When Auto Reset Is Missing

If you use an external USB-serial adapter, the board may not auto-toggle reset and boot pins. You can still flash, yet you may need to press Reset once the write completes. If timing feels finicky, repeat the same steps in the same order so you can spot what changes.

Notes For Newer ESP32 Variants

ESP32-S2, ESP32-S3, and ESP32-C3 boards often work fine with Improv. Some newer chips like ESP32-C6 have had reports of Improv detection failures in some ESPHome releases. If your board is a C6 and a reset does nothing, try the newest ESPHome Web build or flash from a local dashboard instead of the browser wizard.

Wi-Fi Fallback Paths When Improv Won’t Trigger

Even if the Improv screen fails, you still have ways to get Wi-Fi onto the device. Many ESPHome images include a captive portal fallback. If the device can’t join your Wi-Fi after repeated attempts, it can start its own hotspot so you can enter credentials in a web page.

Use The Hotspot Portal

• Scan for a new SSID — Look for a setup hotspot name that matches the device or the flashed image.
• Join the hotspot — Connect to it in your Wi-Fi settings, then open 192.168.4.1 in a browser.
• Type credentials carefully — Re-enter SSID and password, then wait for the device to reboot and join your network.

Network Details That Trip People Up

Even when Improv works, Wi-Fi can still fail at the join step. Most ESP devices connect on 2.4 GHz only. If your router has a 5 GHz only SSID, or if you picked the wrong band name from a long list, the device will loop, fail, then start its hotspot fallback.

• Pick a 2.4 GHz network — Use an SSID that is available on 2.4 GHz so the device can join.
• Avoid special characters — If your Wi-Fi password uses uncommon symbols, try a simpler password during setup, then change it later.
• Stay close to the router — Do the first join within a few meters so weak signal is not part of the problem.

Find The IP On Your Router

If your router shows a new client device, open the IP address in your browser. If you use an ESPHome dashboard, you can add the device by IP and then push your real YAML config over the network.

At this point, the browser error can be misleading. The serial handoff may have failed, yet the device is already on Wi-Fi and ready for the next step.

Config Choices That Prevent Repeat Setup Headaches

If you build your own ESPHome firmware, you can make Improv far more reliable by including the pieces it needs and keeping a recovery path ready. The Improv serial feature needs the serial logger plus the improv_serial component. Without those, the browser cannot complete the Improv flow even if everything else is fine.

What To Include In A Custom YAML

• Keep logger enabled — Leave the serial logger on during setup so Improv can run.
• Add improv_serial — Include the improv_serial block so the firmware answers Improv over USB.
• Enable captive_portal — Allow a fallback hotspot if the device can’t join Wi-Fi.

If you want a quick sanity check, this is the core shape many setups use during onboarding. Adjust names and secrets to match your own install.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "esphome-fallback"
    password: !secret ap_password

captive_portal:

logger:

improv_serial:

If you later need silent logs, you can adjust logger settings after the device is stable on Wi-Fi. For first setup, leave yourself an easy way back in.

Deep Checks When Nothing Else Works

If the message persists after resets, cable swaps, and hotspot attempts, isolate the problem. You want to prove whether the serial link is alive and whether the firmware is running.

What The Logs Tell You

If the log window shows repeated resets, look for power issues or a bad cable. If it shows only a bootloader header and no normal startup banner, treat it as a boot mode problem. If it shows normal startup logs, then the device is running firmware and the Improv part is what the browser can’t see.

Verify Serial Output

1. Open a serial terminal — Connect at 115200 and watch for boot text.
2. Press Reset — You should see a boot message or logs.
3. Close the terminal — Quit it fully, then return to the web installer and retry.

If you see no output at all, treat it as a hardware or driver issue. If you see clean logs yet Wi-Fi setup still fails, the Improv service may not be running in the flashed image.

Clean Reflash With A Cold Boot

1. Erase then flash — If your tool offers erase, run it once, then flash again.
2. Reset right after the write — Tap Reset as soon as the flash completes.
3. Retry the same port — Reconnect to the same port and try Wi-Fi setup once more.

Two reminders catch a lot of cases. First, if you see “an error occurred — improv wi-fi serial not detected” right after a successful flash, reset the board before retrying. Second, if you keep seeing “an error occurred — improv wi-fi serial not detected” across clean reflashes, test on a different computer or a different USB-serial path to rule out the host side.