The C++ undefined reference error is a link-time error: individual compilation (g++ -c) succeeds because a declaration is present, but the linker (/usr/bin/ld invoked via collect2) cannot find a matching definition (T) for an unresolved symbol (U). Using four real cases and nm outputs reproduced on 2026-10-28 (KST) with g++/gcc (Debian 14.2.0-19) 14.2.0 on x86_64 and /usr/bin/ld, this post walks through each cause and fix (offsets such as +0x5 are specific to this environment, and temporary object paths are shown as /tmp/ccXXXXXX.o).

Summary

An undefined reference comes from the linker rather than the compiler: the compiler saw a declaration promising the function exists, but the linker could not find the function body across any of the linked objects or libraries. The four classic causes are forgetting to write the definition, omitting the implementation .cpp file or library from the link command, calling a C function from C++ without extern "C", or placing a static library flag (-l) before the object file that depends on it. Comparing U (undefined) and T (defined in the text section) with nm and nm -C pinpoints which case applies.

What is the undefined reference error?

One-line answer: The undefined reference error is a link error raised by ld (ending with ld returned 1 exit status) after compilation (g++ -c) succeeds, when a declared symbol (U) has no matching definition (T) in the linked objects or libraries.

Under separate compilation in C++, a declaration is enough for the compiler to turn a source file into an object file (.o). When building the final executable, however, the linker must resolve every referenced symbol to an actual definition.

Consider c1_main.cpp, which declares helper() without defining it (the comment in the code means “declaration only”):

void helper();   // 선언만 있음
int main() { helper(); }

Building an executable with $ g++ c1_main.cpp -o c1 fails with exit=1:

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c1_main.cpp:(.text+0x5): undefined reference to `helper()'
collect2: error: ld returned 1 exit status

Compiling without linking via $ g++ -c c1_main.cpp -o c1_main.o succeeds with exit=0. Inspecting the resulting object file with $ nm -C c1_main.o shows:

                 U helper()
0000000000000000 T main

In nm output, T marks a symbol defined in the object’s text (code) section, whereas U marks a symbol referenced by this file but not defined in it. This is the exact opposite of the duplicate-symbol link failure covered in What is the C++ “multiple definition” error? Why a function defined in a header needs inline (defined zero times vs. defined twice), and it also differs from compile-time syntax or macro failures such as What is the “expected unqualified-id before numeric constant” error? How to fix C++ macro name clashes. The fundamentals of separate compilation are also covered in A Tour of C++ 3.2 — Separate Compilation: Headers vs C++20 Modules.

The linker searches object files and libraries for a definition T matching an unresolved symbol U

What happens when a definition file is omitted from the build?

One-line answer: Including the header satisfies the compiler, but leaving the implementation .cpp file out of the link command leaves the symbol unresolved.

Here the declaration and definition are split across math.h and math.cpp, and c2_main.cpp calls add:

// math.h
#pragma once
int add(int a, int b);
// math.cpp
#include "math.h"
int add(int a, int b) { return a + b; }
// c2_main.cpp
#include "math.h"
#include <cstdio>
int main() { std::printf("add=%d\n", add(2, 3)); }

Running $ g++ c2_main.cpp -o c2 without math.cpp fails with exit=1:

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c2_main.cpp:(.text+0xf): undefined reference to `add(int, int)'
collect2: error: ld returned 1 exit status

Passing both source files with $ g++ c2_main.cpp math.cpp -o c2 succeeds with exit=0, and running $ ./c2 prints:

add=5

In a CMake project, make sure every implementation .cpp file is listed in the add_executable (or library target) source list.

Why does it happen when calling a C function from C++?

One-line answer: The C++ compiler mangles the function name (_Z8c_squarei) while the C compiler exports the unmangled name (c_square), so the linker sees two different symbol names unless the declaration uses extern "C".

As documented on cppreference under Language linkage, extern "C" specifies C language linkage so that a C++ program can call functions compiled as C without C++ name mangling.

Suppose csq.c is compiled as C with gcc -c csq.c -o csq.o:

int c_square(int x) { return x * x; }

And c3_main_bad.cpp includes csq_noextern.h (which declares int c_square(int x); without extern "C"):

#include "csq_noextern.h"
#include <cstdio>
int main() { std::printf("sq=%d\n", c_square(4)); }

Linking them together with $ g++ c3_main_bad.cpp csq.o -o c3bad fails with exit=1 even though csq.o is on the command line:

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c3_main_bad.cpp:(.text+0xa): undefined reference to `c_square(int)'
collect2: error: ld returned 1 exit status

Checking both object files with nm shows why. Running $ nm csq.o outputs:

0000000000000000 T c_square

Running $ nm c3_main_bad.o shows the mangled symbol requested by the C++ caller:

                 U _Z8c_squarei
0000000000000000 T main
                 U printf

And demangling with $ nm -C c3_main_bad.o displays:

                 U c_square(int)
0000000000000000 T main
                 U printf

Because csq.o defines c_square while c3_main_bad.o asks for _Z8c_squarei, the linker cannot match them.

The C compiler exports c_square while the C++ caller looks for _Z8c_squarei, a name mangling mismatch

To fix this in a header shared between C and C++, wrap the declaration in an #ifdef __cplusplus guard with extern "C" in csq.h:

#ifdef __cplusplus
extern "C" {
#endif
int c_square(int x);
#ifdef __cplusplus
}
#endif

Replacing the header in c3_main_bad.cpp with #include "csq.h" to form c3_main_ok.cpp and running $ g++ c3_main_ok.cpp csq.o -o c3ok succeeds with exit=0. Running $ ./c3ok prints:

sq=16

Why does static library order matter on the command line?

One-line answer: The linker processes object files and static libraries in the order they appear on the command line, so -l must come after the object files that reference its symbols.

As the GCC Link Options manual states: “the linker searches and processes libraries and object files in the order they are specified” and “If bar.o refers to functions in ‘z’, those functions may not be loaded.” Consequently, you should place -l options after the object files that reference them.

Suppose we package math.cpp into a static library with g++ -c math.cpp -o math.o && ar rcs libmymath.a math.o. Putting -lmymath before c2_main.cpp in $ g++ -L. -lmymath c2_main.cpp -o c4bad fails with exit=1:

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c2_main.cpp:(.text+0xf): undefined reference to `add(int, int)'
collect2: error: ld returned 1 exit status

Moving -L. -lmymath after c2_main.cpp in $ g++ c2_main.cpp -L. -lmymath -o c4ok succeeds with exit=0, and running $ ./c4ok outputs:

add=5

How do you diagnose the cause with nm?

One-line answer: Follow a three-step check comparing the caller object’s U symbols with the provider object or library’s T symbols using nm and nm -C.

  1. Run nm -C on the calling object file (.o) to confirm the exact U symbol that is unresolved.
  2. Run nm -C on the object file (.o) or static library (.a) that should define the symbol to see whether a matching T entry exists.
  3. If raw nm (without -C) shows an unmangled C symbol (T c_square) vs. a mangled C++ symbol (U _Z8c_squarei), add extern "C"; if T is absent or was skipped, add the missing file/library to the link command or move -l after the caller.

What are the frequently asked questions?

One-line answer: Defining templates in a .cpp file, omitting a virtual function definition, or linking against the wrong target architecture during cross compilation can also cause undefined reference errors.

Why does defining a function template in a .cpp file cause a link error?

The compiler needs to see a template’s full definition at the point of instantiation, so as a general rule template definitions should stay in the header file unless you provide explicit instantiations.

What happens if a virtual function is declared but never defined?

If a non-pure virtual function is declared without a definition, vtable may appear in the linker message. For background on virtual functions and destructors, see What is a virtual destructor in C++? Why delete through a base pointer needs virtual.

Why does the error occur during cross compilation even when the library is specified?

Pointing the linker at a host-architecture library or the wrong sysroot can leave target symbols unresolved; see What is cross-compilation? Steps to build with ARM gcc and run on QEMU for the cross-build workflow.

One-line answer: These related posts cover C++ link and compile errors, virtual destructors, cross compilation, and CMake toolchain files.

What are the sources?

One-line answer: This post references the official GCC Link Options manual and the cppreference Language linkage documentation.