What is an undefined reference/unresolved external symbol error and how do I fix it?

c++, c++-faq, linker-errors, undefined-reference, unresolved-external

Solution

Say you have the following code:

// a.cpp
int get() { return 0; }

// b.cpp
int get(); // usually, one doesn't write this directly, but gets these
           // declarations from included header files
int x = get();

When compiling `b.cpp`, the compiler simply assumes that `get()` symbol was defined somewhere, but it doesn't yet care where. The linking phase is responsible for finding the symbol and correctly linking the object files produced from `a.cpp` and `b.cpp`.

If `a.cpp` didn't define `get`, you would get a linker error saying "undefined reference" or "unresolved external symbol".

C++ Standard Wording

Compiling a C++ program takes place in several phases specified in [lex.phases], the last of which is relevant:

9. All external entity references are resolved. Library components are linked to satisfy external references to entities not defined in the current translation. All such translator output is collected into a program image which contains information needed for execution in its execution environment.

See Keith Thompson's answer for a summary of these phases.

The specified errors occur during this last stage of compilation, most commonly referred to as linking. It basically means that you compiled a bunch of source files into object files or libraries, and now you want to get them to work together.

Linker Errors in Practice

If you're using Microsoft Visual Studio, you'll see that projects generate `.lib` files. These contain a table of exported symbols, and a table of imported symbols. The imported symbols are resolved against the libraries you link against, and the exported symbols are provided for the libraries that use that `.lib` (if any).

Similar mechanisms exist for other compilers/ platforms.

Common error messages are `error LNK2001`, `error LNK1120`, `error LNK2019` for Microsoft Visual Studio and `undefined reference to` symbolName for GCC.

The code:

struct X
{
   virtual void foo();
};
struct Y : X
{
   void foo() {}
};
struct A
{
   virtual ~A() = 0;
};
struct B: A
{
   virtual ~B(){}
};
extern int x;
void foo();
int main()
{
   x = 0;
   foo();
   Y y;
   B b;
}

will generate the following errors with GCC:

/home/AbiSfw/ccvvuHoX.o: In function `main':
prog.cpp:(.text+0x10): undefined reference to `x'
prog.cpp:(.text+0x19): undefined reference to `foo()'
prog.cpp:(.text+0x2d): undefined reference to `A::~A()'
/home/AbiSfw/ccvvuHoX.o: In function `B::~B()':
prog.cpp:(.text._ZN1BD1Ev[B::~B()]+0xb): undefined reference to `A::~A()'
/home/AbiSfw/ccvvuHoX.o: In function `B::~B()':
prog.cpp:(.text._ZN1BD0Ev[B::~B()]+0x12): undefined reference to `A::~A()'
/home/AbiSfw/ccvvuHoX.o:(.rodata._ZTI1Y[typeinfo for Y]+0x8): undefined reference to `typeinfo for X'
/home/AbiSfw/ccvvuHoX.o:(.rodata._ZTI1B[typeinfo for B]+0x8): undefined reference to `typeinfo for A'
collect2: ld returned 1 exit status

and similar errors with Microsoft Visual Studio:

1>test2.obj : error LNK2001: unresolved external symbol "void __cdecl foo(void)" (?foo@@YAXXZ)
1>test2.obj : error LNK2001: unresolved external symbol "int x" (?x@@3HA)
1>test2.obj : error LNK2001: unresolved external symbol "public: virtual __thiscall A::~A(void)" (??1A@@UAE@XZ)
1>test2.obj : error LNK2001: unresolved external symbol "public: virtual void __thiscall X::foo(void)" (?foo@X@@UAEXXZ)
1>...\test2.exe : fatal error LNK1120: 4 unresolved externals

Common Causes

- Failure to link against appropriate libraries/object files or compile implementation files

- Declared and undefined variable or function.

- Common issues with class-type members

- Template implementations not visible.

- Symbols were defined in a C program and used in C++ code.

- Incorrectly importing/exporting methods/classes across modules/dll. (MSVS specific)

- Circular library dependency

- undefined reference to `WinMain@16'

- Interdependent library order

- Multiple source files of the same name

- Mistyping or not including the .lib extension when using the `#pragma` (Microsoft Visual Studio)

- Problems with template friends

- Inconsistent `UNICODE` definitions

- Missing "extern" in const variable declarations/definitions (C++ only)

- Visual Studio Code not configured for a multiple file project

- Errors on Mac OS X when building a dylib, but a .so on other Unix-y systems is OK

- Your linkage consumes libraries before the object files that refer to them

Problem

What are undefined reference/unresolved external symbol errors? What are common causes, and how do I fix and prevent these errors?

Original source

Related problems