← Back to guides

Fix Arduino Compile Errors

LiquidCrystal · HD44780 · Common mistakes

Most LCD 1602 problems fall into a few categories: missing libraries, wrong constructor arguments, pin conflicts, or incorrect custom character syntax. This guide covers the errors beginners hit most often.

'LiquidCrystal' was not declared in this scope

Cause: Missing #include or wrong library for your module type.

Fix:

// Parallel LCD:
#include <LiquidCrystal.h>

// I2C backpack (install via Library Manager):
#include <Wire.h>
#include <LiquidCrystal_I2C.h>
LiquidCrystal_I2C lcd(0x27, 16, 2);

no matching function for call to 'LiquidCrystal::LiquidCrystal(...)'

Cause: Wrong number of pin arguments.

Fix: 4-bit mode needs exactly 6 pins — RS, E, D4, D5, D6, D7:

LiquidCrystal lcd(RS, E, D4, D5, D6, D7);
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);

conflicting declaration / redefinition of 'byte customChar'

Cause: Same array name defined twice, or pasted code inside another array.

Fix: Define each custom character once at global scope with unique names:

byte iconHeart[8] = { ... };
byte iconWifi[8]  = { ... };

Custom character shows garbage or wrong shape

  • Verify 8 bytes exactly — not 7, not 9
  • Ensure hex values use 0x prefix: 0x1F not 1F
  • Call lcd.createChar() before lcd.write(byte(n))
  • Slot number in createChar(n, ...) must match write(byte(n))
  • Re-generate bytes with the pixel tool to rule out typos

Display works but icons disappear after reboot

CGRAM is volatile — custom characters must be reloaded in every setup(). Store byte arrays in flash (PROGMEM) if RAM is tight, but always call createChar() on boot.

Sketch uploads but LCD stays blank

  • Adjust contrast potentiometer — most common fix
  • Confirm RW pin (pin 5) is tied to GND
  • Check wiring pinout — swapped D4/D5 is a frequent mistake
  • For I2C: scan address with I2C scanner sketch (0x27 or 0x3F)

Still stuck?

Copy your byte array from the generator, paste into a minimal sketch with only begin, createChar, and write — isolate hardware vs. code issues. See also custom icons guide for a working example.