Troubleshoot by symptom

The board is plugged in, but it is not in the port list

What it looks like

You click Start flashing, the browser opens the port picker, and it is empty — or it lists only the Bluetooth serial ports your computer already had. There is no error message, which is exactly what makes it hard: nothing happens on screen.

What is actually going on (most common first)

1. The cable carries power but not data. Number one, by a wide margin. With a charge-only cable the board's power LED lights up and everything looks fine, but the computer has no idea it exists.
2. The USB-to-serial driver is missing. The small chip on the board that converts USB to serial (usually CH340 or CP2102) needs a driver. On Windows and on some macOS versions you install it by hand.
3. It is plugged into a port that carries no data. Some hubs, and some USB ports on keyboards, supply power only.
4. The board has no USB-to-serial chip at all. Some modules — as opposed to dev boards — need an external USB-TTL adapter before they can be flashed.

What to do

1. Change the cable. Use one you know carries data — the one you use to move files to your phone, for example. This step alone clears most cases.
2. Change the USB port. Plug straight into the computer, not through a hub.
3. Still nothing: install the driver. Read the marking on that small chip (CH340 / CP2102 / CP2104) and search for the official driver for that part. After installing, unplug and replug the cable.

You clicked flash and the browser never opened the port picker

What it looks like

The button does nothing, or the page says This browser does not support serial flashing. Use Chrome or Edge.

What is actually going on

Flashing in the browser depends on WebSerial, a capability only Chromium-based browsers have. Firefox and Safari do not have it, and will not any time soon — that is a decision by those browser vendors, not a limitation of ours.

What to do

1. Switch to Chrome, Edge or another Chromium-based browser and open this page again.
2. Or keep your browser: click Download to get the firmware, and flash it with the tool you already use (esptool, Arduino IDE, Espressif's own flashing tool). How to download →

Flashing fails the moment it starts, or stalls at some percentage

What it looks like

The port is selected, the progress bar moves a little and stops, and the log shows Failed to open serial port., No serial data received. or Failed to connect with the device. These are three separate errors — they never appear joined together, so search for them exactly as written.

What is actually going on

What you see	What it actually means
Failed to open serial port.	Another program is holding that serial port. This is the browser's fixed wording when it cannot open the port; it reads like a permission problem, and it is not. The three usual holders: an Arduino IDE with the serial monitor open, a browser tab from last time that you never closed, another serial tool. (While this page's own Console is connected, Start flashing is greyed out and cannot be clicked, so you never get this far that way.) If you are flashing from the command line with esptool.py instead of the browser, the same situation reads Access is denied. on Windows.
No serial data received. Failed to connect with the device	The board did not enter flash mode. The flashing library throws these two separately; usually only one of them shows up. Most dev boards enter flash mode on their own; a few need you to do it by hand: hold BOOT down, plug the cable in (or tap RESET), then release BOOT.
It reaches some percentage and stays there	Usually a bad cable contact or not enough power. Waiting does not help — this is not a network transfer; stalled is stalled.

What to do

1. Disconnect the Console and close everything that could be holding the port (Arduino IDE, other serial tools, another tab with this project open).
2. Click flash again.
3. Still No serial data received.: hold BOOT down, tap RESET, release RESET first and BOOT second, then retry the flash immediately.
4. Still stalling: change the cable, and use a USB port directly on the computer.

The serial port connects, but everything it prints is garbage

What it looks like

The Console keeps producing output, but it is all unreadable characters like ÿÿ��@�. Sometimes the first few lines are fine and it turns to garbage after that.

What is actually going on

1. The baud rate is wrong. Number one. The rate you chose when connecting does not match the rate the firmware sets, so what you read is garbage. The convention here is 115200.
2. First few lines garbled, the rest fine: this is not a fault. The first lines after a reset come from the chip's built-in ROM, and the rate it uses is not necessarily the rate the firmware sets. Once the firmware takes over the output is readable. Keep reading below them.
3. Garbage all the way through with the baud rate confirmed correct: usually a bad ground, or an unsuitable USB-TTL adapter.

What to do

1. Disconnect the Console, click Connect device again, and set Baud rate to 115200.
2. Still garbage: try 9600. If your board is an ESP8266, also try 74880 — that is the ESP8266 bootloader rate; the ESP32 family ROM uses 115200.
3. If none of them work, send this in the chat: The serial output is garbled — tell me which baud rate the firmware sets.

The board reboots over and over after flashing

What it looks like

Every second or two the Console reprints the boot banner, with Guru Meditation Error, abort() or rst:0xc (SW_CPU_RESET) in between.

What is actually going on

The firmware has started running, crashes at one step of initialization, and the watchdog restarts it — around and around. The most common cause is a hardware mismatch: the code initializes the sensor on the pins from the plan, and the pins you actually wired are different, or nothing is wired at all.

What to do

1. Scroll up in the Console and find the last line before the crash — that line usually names what it was initializing at the time.
2. Copy the whole stretch of log from the reset to the crash.
3. Paste it into the project chat and add a line: It keeps rebooting after flashing. Here is the serial log — tell me which step it dies on.
4. At the same time, check your actual wiring against the pin connection table.

The build keeps failing

What it looks like

A build-failure message shows up in the chat. Which kind it is shows on the "Failed stage" line inside Build output in the Main pane — word for word as in the table below, followed by an action (for example · User action required). There are seven kinds, and each belongs to a different side. Read which one it is before deciding whether you need to act.

The wording on "Failed stage"	Whose problem it is	What you do
Firmware project needs repair	The platform fixes it	Nothing to do; wait for the retry. Most build failures are this kind
Hardware selection needs attention	Yours	This hardware yields no build target. Go back to the chat and switch to a supported board, or fill in the full model number
Build profile needs backend attention	Platform	Report it to us
Compile workflow needs backend attention	Platform	Report it to us
Compile service needs attention	Platform	Retry later
Compile resource unavailable	Platform	Retry later
Compile safety check blocked output	Needs a human to confirm	Report it to us

A few outcomes carry no "Failed stage" line at all. They show on the "Compile" line higher up in the same panel: Queue timed out, Build timed out, System error, Cancelled. Retry the first three directly — that is resource pressure, not a problem in your code. Cancelled means that round was stopped, usually because you pressed the stop button on the chat box; say it again to start over.

What to do

1. Read which kind it is. Only Hardware selection needs attention needs you; the rest sit on the platform side.
2. If it is the hardware kind: go back to the chat and state exactly which board and which modules you actually have.
3. If it is one of the timeouts, or it was cancelled: send Build it again.
4. Several rounds in a row with the same error: copy the failure message it gave you, then send Three rounds in a row with this same error — try a different approach.

It says the hardware is "Unsupported"

What it looks like

The hardware-support badge in the header reads Unsupported or Needs more info instead of "Recommended" or "Can try".

What is actually going on

Today the platform has two frameworks, esp-idf and arduino. The boards it can build firmware for are: the ESP32 family (esp32 / s2 / s3 / c2 / c3 / c6 / h2), ESP8266 dev boards, and the Arduino Uno. It would rather tell you up front that something is unsupported than pretend it can do it and blow up at build time. That is deliberate.

"Needs more info" is a different thing. It is not saying no; it is saying what you have given it is not enough to judge. Adding the model number usually clears it.

What to do

1. First check which of the two it is. If it is "Needs more info", give the board's full model number — the string printed on the silkscreen.
2. If it really is unsupported: switch to a board in the ESP32 family. ESP32-C3 and ESP32-S3 are the two safest routes.
3. If that board is all you have and you do not want to switch: you can ask it to plan around the closest chip, but know that a build that passes is not the same as firmware that runs on your board.

You sent something and nothing comes back

What it looks like

The message went out, the interface keeps showing a "working on it" state, and no new content arrives for a long time.

What is actually going on

1. It really is running. Writing the code plus one build round usually takes a few minutes. There is deliberately no percentage progress bar here — that number would be invented. What you get instead is the step it is on right now.
2. The push channel dropped. The result arrives but you do not see it. The Realtime indicator does not change colour when this happens — a dropped socket just reconnects quietly in the background, so it cannot tell you.
3. This round used up its execution budget. It says so plainly, and you can continue from there.

What to do

1. First check whether the status in the header is still changing. If it is, that is normal — wait.
2. Just refresh the page — refreshing loses nothing; this round is still running in the background. A refresh re-fetches the result, which is more use than watching that indicator.
3. If after the refresh there is still nothing new and it has been more than thirty minutes (that is the order of the per-build cap): send That last round looks like it dropped — run it again.

The code changed, but flashing gives the same old behaviour

What it looks like

You can see the change in the Code panel, but the board behaves exactly as before. The interface may say: The source has changed; the current firmware still comes from the last successful build.

What is actually going on

"The source changed" and "what runs on the board changed" are two different things, with two steps in between: building, and flashing. This is the concept beginners trip over most. Editing the source only changes the project in the cloud; it has to be built into firmware again, and you have to flash it again, before the board's behaviour changes.

If you come from software development

There is no hot reload here, and no docker restart. The chain is source → build → firmware file → flash → device. Each of the four links carries its own state, and if one link is skipped, everything downstream is stale.

That line in the interface — "The source matches the latest build" / "The source has changed" — is telling you whether the first two links line up. The flashing link has no indicator at all: the platform does not know what is running on your board, only you know which version you flashed last.

What to do

1. Confirm that it has actually rebuilt — read the build status line and see whether it says "The source matches the latest build" or "The source has changed".
2. If it has not built yet, send Build it again in the chat.
3. When the build finishes, flash it again. Without a new flash the board keeps running the old firmware forever.

The Console says "This browser does not support the serial console."

What it looks like

You switch to the Console panel, this line is all the log area shows, and the Connect device button is greyed out and cannot be clicked. The button is still there; it is only disabled.

What is actually going on

The same cause as flashing: WebSerial exists only in Chromium-based browsers.

What to do

Switch to Chrome or Edge. The serial log has no download fallback — it has to read from the device live, so there is no other way through this step in the product. Outside the product there is one more route: read it with any serial tool on your computer (screen, PuTTY, the Arduino IDE serial monitor) and copy the log into the chat box.

The log is long — paste it anyway, an over-long paste becomes an attachment

What it looks like

Pasting itself works. If the paste would push the message over the limit, the text does not go into the box: it turns into a pasted-….log file entry below the box, with the notice The pasted text is 12345 characters, over the 8000 limit, so it became the attachment pasted-20260908-101530-a1b2.log (48.2 KB). Write a line in the box saying what you want me to look at.

What is actually going on

A single project-chat message holds at most 8,000 characters. A paste that stays under the limit goes into the box exactly as before; only the one that goes over is converted. What you get is an ordinary attachment, no different from a file you dragged in yourself.

What to do

1. After pasting, be sure to write a line saying what you want it to look at, for example This is the serial output after flashing; it keeps rebooting — tell me where it gets stuck. An attachment with an empty message will not send; the interface says Say what you uploaded and what you want done with it.
2. If the log is already a file, drag the .log straight into the input box — same result.
3. Or paste only the part that matters: from the reset to the crash is usually enough.