Troubleshooting Arduino and ESP32¶

Even with good wiring and code, things will sometimes not work on the first try. This page lists common problems and quick checks to help you debug faster.

1. Board not detected by the IDE¶

Symptoms:

The correct COM port is not visible.
Upload fails immediately with a “no serial port” error.

Checks:

Try a different USB cable (some cables are power‑only).
Try a different USB port on your laptop.
Make sure no other application is using the same serial port.
Confirm you selected the correct board type (e.g. ESP32-S3 Dev Module, ESP32-C3 Dev Module).

ESP32 with Macbooks ARM architecture

On the Macbooks with ARM architecture, the ESP32-S3 Dev Module is not supported out of the box. To make it work you need to install the MacOS driver. There are two versions of the driver for different chipsets. Recommended is to install both drivers and reboot the machine.

We know these websites are sketchy and sometimes in Chinese, but we have not found a better source.

After installation you can verify if the driver is installed correctly if you can find a board in the Arduino IDE starting with ‘/dev/cu.wchusbserial…’ (instead of only ‘/dev/cu/cu.usbserial’).

2. Sketch does not upload¶

Symptoms:

Upload starts but ends with timeouts or sync errors.
ESP32 error messages about boot / flash mode.

Checks:

Verify the selected board and port in the Arduino IDE.
Press and release the EN/RESET button once and try again.
On some ESP32‑C3 or Supermini boards:
Hold the BOOT button, press RESET, then release RESET and then BOOT to enter boot mode.

If nothing helps, disconnect all external wiring and try to upload a simple Blink sketch to rule out short circuits on your breadboard.

3. Program uploads but “nothing happens”¶

Symptoms:

Upload succeeds, but no LED, no output, no visible behavior.

Checks:

Double‑check pin numbers in your sketch against the board’s pinout.
Add Serial.println("setup() running"); to confirm that the code actually runs.
Make sure you have called pinMode(pin, OUTPUT) for pins that drive LEDs or other outputs.
Check the Serial Monitor baud rate matches Serial.begin(...).

4. Random resets or unstable behavior¶

Symptoms:

The board resets unexpectedly.
Wi‑Fi disconnects often or code seems to restart.

Checks:

Power:
Avoid powering motors, servos, or many LEDs directly from the ESP32-S3’s 3.3 V pin.
Use a stable external power supply for high‑current devices and share GND.
Wiring:
Check for loose connections or accidental shorts on the breadboard.
Keep high‑current wires away from sensitive analog signal wires.

5. Sensor values look wrong¶

Symptoms:

Constant 0 or constant maximum value.
Very noisy or jumping readings.

Checks:

Confirm the sensor is connected to an ADC‑capable pin (see the ESP32 pinout page).
Use Serial.println(...) to print raw values and verify they change when you expect.
Make sure the sensor has:
Correct power voltage (3.3 V vs 5 V).
A proper ground connection.
For analog sensors (potentiometer, LDR), verify the voltage divider is wired correctly.

6. Wi‑Fi / network issues¶

Symptoms:

Cannot connect to Wi‑Fi.
HTTP requests always fail.

Checks:

Double‑check SSID and password (case‑sensitive).
Verify the ESP32-S3 is on the expected network (for example the iotroam network on campus).
Print WiFi.status() to the Serial Monitor during connection attempts.
On a laptop, try to reach the same API endpoint with a browser or curl to confirm it is accessible.

When you run into problems, break them down:

First: Does the simple Blink/Serial sketch work?
Then: Does the wiring look correct?
Finally: Is your logic doing what you think? (use lots of Serial.println(...)).