ld.lld: undefined symbol: loop() Explained and Fixed

You press Run and the Build tab fills with red text. One line says ld.lld: error: undefined symbol: loop(), and unlike most errors it has no line number and nothing to click. In this post you will see exactly why that happens, how to fix it in under a minute, and how to tell this kind of error apart from the compiler errors that do point at a line. We will use a tiny Arduino Uno blink sketch, and I checked every version of it in Mokxi's own build.

Two kinds of build errors

Building a sketch takes two stages. The first is the compiler. It reads your code line by line and turns each function into machine instructions. When it finds something it cannot understand, it stops and tells you the file, the line and the column.

The second stage is the linker. Its job is to join all the pieces into one program and make sure every function that gets called actually exists somewhere. When a piece is missing, the linker reports the missing name. It has no line to point at, because it is not reading your code anymore. It is checking a list of names.

The Mokxi help page on sketches that do not compile says it directly: a position in your sketch is a position in your sketch, and a linker error has no position. It appears as a line without a jump, because there is nothing to jump to.

What you need

A blink circuit on the Arduino Uno board, with one LED and a 220 ohm resistor.

From	To	Why
Uno pin 8	220 ohm resistor, first leg	Limits the current
220 ohm resistor, second leg	LED anode (long leg)	Current flows into the LED
LED cathode (short leg)	Uno GND	Completes the circuit

The working sketch first

const int LED_PIN = 8;

void setup() {
  pinMode(LED_PIN, OUTPUT);
  Serial.begin(9600);
  Serial.println("Blink with a status line");
}

void loop() {
  digitalWrite(LED_PIN, HIGH);
  Serial.println("LED on");
  delay(500);
  digitalWrite(LED_PIN, LOW);
  Serial.println("LED off");
  delay(500);
}

It builds, the LED blinks every half second, and the serial monitor prints "LED on" and "LED off" in turn.

Line by line: LED_PIN names the pin. setup() runs once, sets the pin as an output and starts serial at 9600 baud. loop() runs over and over: it lights the LED, prints a message, waits half a second, turns the LED off, prints again and waits again.

Break it: a typo in loop

Now change one word. Rename loop to lop:

void lop() {
  digitalWrite(LED_PIN, HIGH);
  delay(500);
  digitalWrite(LED_PIN, LOW);
  delay(500);
}

Nothing in this file is wrong as C++. lop() is a perfectly good function with a perfectly good name. The compiler builds it without complaint. The trouble comes at link time, and the Build tab shows:

ld.lld: error: undefined symbol: loop()
>>> referenced by main.cpp:44

Here is what happened. Mokxi's runtime has its own main(), and main() calls setup() once and then calls loop() forever. That call to loop() is the "reference" in the message. The linker went looking for a function called loop, found only lop, and gave up. The main.cpp in the message is the runtime's file, not yours, which is another clue that the problem is a missing name and not a mistake on a line you wrote.

Fix it

Check the spelling. The fix is to rename lop back to loop, with a lowercase l and parentheses, returning void.

The same message appears for other near misses, and I tried them to be sure:

• A capital letter. void Loop() is a different function from void loop(), because C++ is case sensitive. The linker reports undefined symbol: loop() again.
• A missing setup. If you rename setup() to something else, the message is the same shape with a different name: undefined symbol: setup().

When you see undefined symbol followed by a function name and a pair of parentheses, ask three questions. Is the function written in my sketch at all? Is it spelled exactly like the name in the message, including capitals? Did it end up inside another function's braces by mistake? The last one often gives a compiler error instead, but it is worth a look.

Contrast: a compiler error

Now put loop back and make a different typo inside it. Change digitalWrite to digitalWrit on the first line of the function:

void loop() {
  digitalWrit(LED_PIN, HIGH);
  delay(500);
  digitalWrite(LED_PIN, LOW);
  delay(500);
}

This time the build stops earlier, in the compiler, and the message is full of detail:

sketch.ino:8:3: error: use of undeclared identifier 'digitalWrit'; did you mean 'digitalWrite'?
    8 |   digitalWrit(LED_PIN, HIGH);
      |   ^~~~~~~~~~~
      |   digitalWrite

Read it left to right. sketch.ino:8:3 is the file, line 8 and column 3. The word error says it is serious. The sentence says what is wrong: digitalWrit was never declared, which is clang's way of saying it does not know that name. Then it makes a guess, digitalWrite, and underlines the exact spot. Click the line in the Build tab and the editor jumps right to it.

The diagnostics are real clang diagnostics, unedited, and the file is compiled under its own name, so the line numbers are yours.

A quick way to tell them apart

What you see	Stage	What to check
sketch.ino:8:3: error: ...	Compiler	Go to that line and column
ld.lld: error: undefined symbol: name()	Linker	Is name() written and spelled right

If the first line of the Build tab has a file and a number, fix that first. If it begins with ld.lld, the compiler was happy and a function name is missing.

What to try next

• Put the typo back and read both messages in the Build tab until the pattern feels familiar.
• Add a function of your own called blinkTwice() and call it from loop(), then misspell it in one place and see which stage complains.
• Read the Arduino compile errors guide, which goes through the common messages one by one, in both GCC's words and clang's.

Ready to build it yourself? Create your free Mokxi account and open the editor in your browser. No installs, no parts to buy.