ESP32 OLED not displaying: complete I2C, address, and library fix guide

Symptoms and likely causes

Correct ESP32 OLED I2C wiring

Most small OLED modules used with ESP32 have four pins: `VCC`, `GND`, `SDA`, and `SCL`. The exact order can differ by module, so read the silkscreen before plugging wires.

Run an I2C scanner before display code

The I2C scanner is the fastest way to separate wiring problems from library problems. If the scanner cannot find the display, your display drawing code will not work.

#include <Wire.h>

void setup() {
  Serial.begin(115200);
  Wire.begin(21, 22); // SDA, SCL
  Serial.println("Scanning I2C...");
}

void loop() {
  byte error, address;
  int devices = 0;

  for (address = 1; address < 127; address++) {
    Wire.beginTransmission(address);
    error = Wire.endTransmission();

    if (error == 0) {
      Serial.print("I2C device found at 0x");
      if (address < 16) Serial.print("0");
      Serial.println(address, HEX);
      devices++;
    }
  }

  if (devices == 0) Serial.println("No I2C devices found");
  delay(3000);
}

SSD1306 vs SH1106: the library matters

Many small OLED modules are advertised generically as “I2C OLED,” but they may use different controllers. SSD1306 and SH1106 displays can look similar, but code written for one may produce a blank or distorted display on the other.

Minimal SSD1306 test code

Use this only after the I2C scanner finds the OLED. If your scanner finds `0x3D`, change the address in the display constructor or initialization according to your library.

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

void setup() {
  Wire.begin(21, 22); // SDA, SCL

  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    while (true) {
      delay(100);
    }
  }

  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println("ESP32 OLED OK");
  display.display();
}

void loop() {}

Hardware checks when the scanner finds nothing

• Inspect the OLED header solder joints. Unsoldered or cracked joints are common.
• Try shorter jumper wires and avoid loose breadboard connections.
• Check whether the OLED breakout already has I2C pullup resistors.
• Try powering from 3.3V first if the module supports it, especially with ESP32 logic.
• Test the OLED with another microcontroller or test another OLED with the same ESP32.
• Make sure you are using an I2C OLED, not an SPI OLED with different pins.

When OLED works alone but fails inside your project

Once the display works by itself, failures inside a larger project usually come from I2C bus conflicts, blocking code, memory pressure, or pin reuse.

• Scan the I2C bus with every module connected and check for address conflicts.
• Make sure another library is not reinitializing `Wire` with different pins.
• Watch memory usage if you use large display buffers, Wi-Fi, JSON, and web servers together.
• Update the display at a reasonable rate instead of redrawing constantly inside heavy loops.

FAQ