What are undefined reference/unresolved external symbol errors? What are common causes and how to fix/prevent them?
39 Answers
An “Undefined Reference” error occurs when we have a reference to object name (class, function, variable, etc.) in our program and the linker cannot find its definition when it tries to search for it in all the linked object files and libraries.
Thus when the linker cannot find the definition of a linked object, it issues an “undefined reference” error. As clear from definition, this error occurs in the later stages of the linking process. There are various reasons that cause an “undefined reference” error.
Some possible reason(more frequent):
#1) No Definition Provided For Object
This is the simplest reason for causing an “undefined reference” error. The programmer has simply forgotten to define the object.
Consider the following C++ program. Here we have only specified the prototype of function and then used it in the main function.
#include <iostream>
int func1();
int main()
{
func1();
}
Output:
main.cpp:(.text+0x5): undefined reference to 'func1()'
collect2: error ld returned 1 exit status
So when we compile this program, the linker error that says “undefined reference to ‘func1()’” is issued.
In order to get rid of this error, we correct the program as follows by providing the definition of the function func1. Now the program gives the appropriate output.
#include <iostream>
using namespace std;
int func1();
int main()
{
func1();
}
int func1(){
cout<<"hello, world!!";
}
Output:
hello, world!!
#2) Wrong Definition (signatures don’t match) Of Objects Used
Yet another cause for “undefined reference” error is when we specify wrong definitions. We use any object in our program and its definition is something different.
Consider the following C++ program. Here we have made a call to func1 (). Its prototype is int func1 (). But its definition does not match with its prototype. As we see, the definition of the function contains a parameter to the function.
Thus when the program is compiled, the compilation is successful because of the prototype and function call match. But when the linker is trying to link the function call with its definition, it finds the problem and issues the error as “undefined reference”.
#include <iostream>
using namespace std;
int func1();
int main()
{
func1();
}
int func1(int n){
cout<<"hello, world!!";
}
Output:
main.cpp:(.text+0x5): undefined reference to 'func1()'
collect2: error ld returned 1 exit status
Thus to prevent such errors, we simply cross-check if the definitions and usage of all the objects are matching in our program.
#3) Object Files Not Linked Properly
This issue can also give rise to the “undefined reference” error. Here, we may have more than one source files and we might compile them independently. When this is done, the objects are not linked properly and it results in “undefined reference”.
Consider the following two C++ programs. In the first file, we make use of the “print ()” function which is defined in the second file. When we compile these files separately, the first file gives “undefined reference” for the print function, while the second file gives “undefined reference” for the main function.
int print();
int main()
{
print();
}
Output:
main.cpp:(.text+0x5): undefined reference to 'print()'
collect2: error ld returned 1 exit status
int print() {
return 42;
}
Output:
(.text+0x20): undefined reference to 'main'
collect2: error ld returned 1 exit status
The way to resolve this error is to compile both the files simultaneously (For example, by using g++).
Apart from the causes already discussed, “undefined reference” may also occur because of the following reasons.
#4) Wrong Project Type
When we specify wrong project types in C++ IDEs like the visual studio and try to do things that the project does not expect, then, we get “undefined reference”.
#5) No Library
If a programmer has not specified the library path properly or completely forgotten to specify it, then we get an “undefined reference” for all the references the program uses from the library.
#6) Dependent Files Are Not Compiled
A programmer has to ensure that we compile all the dependencies of the project beforehand so that when we compile the project, the compiler finds all the dependencies and compiles successfully. If any of the dependencies are missing then the compiler gives “undefined reference”.
Apart from the causes discussed above, the “undefined reference” error can occur in many other situations. But the bottom line is that the programmer has got the things wrong and in order to prevent this error they should be corrected.
When you are using a wrong compiler to build your program
If you are using gcc
or clang
compiler suites, you should use the right compiler driver according to the language you are using. Compile and link C++ program using g++
or clang++
. Using gcc
or clang
instead will cause references to the C++ standard library symbols to be undefined. Example:
$ gcc -o test test.cpp
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/../../../../x86_64-pc-linux-gnu/bin/ld: /tmp/ccPv7MvI.o: warning: relocation against `_ZSt4cout' in read-only section `.text'
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/../../../../x86_64-pc-linux-gnu/bin/ld: /tmp/ccPv7MvI.o: in function `main': test.cpp:(.text+0xe): undefined reference to `std::cout'
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/../../../../x86_64-pc-linux-gnu/bin/ld: test.cpp:(.text+0x13): undefined reference to `std::basic_ostream<char, std::char_traits<char> >& std::operator<< <std::char_traits<char> >(std::basic_ostream<char, std::char_traits<char> >&, char const*)'
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/../../../../x86_64-pc-linux-gnu/bin/ld: /tmp/ccPv7MvI.o: in function `__static_initialization_and_destruction_0(int, int)':
test.cpp:(.text+0x43): undefined reference to `std::ios_base::Init::Init()'
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/../../../../x86_64-pc-linux-gnu/bin/ld: test.cpp:(.text+0x58): undefined reference to `std::ios_base::Init::~Init()'
/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/../../../../x86_64-pc-linux-gnu/bin/ld: warning: creating DT_TEXTREL in a PIE
collect2: error: ld returned 1 exit status
Some typo errors to consider: (happened to me as a beginner a lot)
- If you are using a class: check if you have not forgetton "classname::" before the function name inside your cpp file where you define the the function.
- If you use forward declaration: be sure to declare the right type. E.g.: if you want to forward declare a "struct" use "struct" and not "class".
-
Actually the only difference between
struct
andclass
is whether the members default to public or private. I can't imagine an example where confusing the two would lead to the error in the question. Sep 27, 2022 at 13:16
Different architectures
You may see a message like:
library machine type 'x64' conflicts with target machine type 'X86'
In that case, it means that the available symbols are for a different architecture than the one you are compiling for.
On Visual Studio, this is due to the wrong "Platform", and you need to either select the proper one or install the proper version of the library.
On Linux, it may be due to the wrong library folder (using lib
instead of lib64
for instance).
On MacOS, there is the option of shipping both architectures in the same file. It may be that the link expects both versions to be there, but only one is. It can also be an issue with the wrong lib
/lib64
folder where the library is picked up.
Using Visual Studio Code with the Code Runner extension and multiple .c or .cpp files
Code Runner as shipped only works with compiled programs that have a single source file. It is not designed for use with multiple source files. You should use a different extension, such as the C/C++ Makefile Project extension or the CMake Tools extension, or perhaps fix the Code Runner extenion to work with multiple files, or just edit your .json configuration files by hand.
My example:
header file
class GameCharacter : public GamePart
{
private:
static vector<GameCharacter*> characterList;
...
}
.cpp file:
vector<GameCharacter*> characterList;
This produced an "undefined" loader error because "characterList" was declared as a static member variable, but was defined as a global variable.
I added this because -- while someone else listed this case in a long list of things to look out for -- that listing did not give examples. This is an example of something more to look for, especially in C++.
The fix is to add qualification to the global variable to define the static data member:
vector<GameCharacter*> GameCharacter::characterList;
While keeping the header the same.
-
This answer doesn't add suitable info for this question. You use not-standard macros(?) defines like TRUE. Thus users searching for an answer here may be overwhelmed by your use of vectors and inheritance.– voidNov 22, 2020 at 11:53
This issue occurred for me by declaring the prototype of a function in a header file:
int createBackground(VertexArray rVA, IntRect arena);
But then defining the function elsewhere using a reference with the first parameter:
int createBackground(VertexArray& rVA, IntRect arena) {}
The fact that the prototype was not using a reference in the first parameter, while the definition was, was causing this issue. When I changed both to properly match either containing a reference or not containing a reference, the issue was fixed.
Cheers.
In my case, The syntax was correct, yet I had that error when a class calls a second class within the same DLL. the CPP file of the second class had the wrong Properties->Item Type
inside visual studio, in my case it was set to C/C++ Header
instead of the correct one C/C++ compiler
so the compiler didn't compile the CPP file while building it and cause the Error LNK2019
here's an example, Assuming the syntax is correct you should get the error by changing the item type in properties
//class A header file
class ClassB; // FORWARD DECLERATION
class ClassA
{
public:
ClassB* bObj;
ClassA(HINSTANCE hDLL) ;
// member functions
}
--------------------------------
//class A cpp file
ClassA::ClassA(HINSTANCE hDLL)
{
bObj = new ClassB();// LNK2019 occures here
bObj ->somefunction();// LNK2019 occures here
}
/*************************/
//classB Header file
struct mystruct{}
class ClassB{
public:
ClassB();
mystruct somefunction();
}
------------------------------
//classB cpp file
/* This is the file with the wrong property item type in visual studio --C/C++ Header-*/
ClassB::somefunction(){}
ClassB::ClassB(){}
I am building a shared/dynamic library. It works on Linux and *BSD, but on Mac OS X the exact same compile and link commands produce unresolved reference errors. What gives?
Mac OS X is very different from Linux and *BSD internally. The object/executable format is
On Linux and *BSD, when building shared libraries, unresolved references are allowed by default. The expectation is that they will be satisfied at load time against the (yet unknown) main executable and/or other shared libraries. If these symbols cannot be resolved at load time, the shared library will fail to load.
On Mac OS X, when building dynamic libraries, unresolved references are not allowed by default. If you expect that a reference should be resolved at load time, you need to enable unresolved references explicitly. This is done with -undefined dynamic_lookup
linker flag.
Allowing unresolved references is useful when building loadable plugins.
this
pointer and no access to class members. It's quite rare to complete compilation and only fail during linking, when a non-static member function is missing its qualified-name.