1763

What are undefined reference/unresolved external symbol errors? What are common causes and how to fix/prevent them?

7
  • @jave.web: While that does happen, the programmer usually notices that he has no 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.
    – Ben Voigt
    Apr 27, 2015 at 22:06
  • @jave.web: This was exactly my problem. Thank you! I am new to cpp, but as far as I can tell, I was having the exact problem that Ben Voigt says was quite rare. I think your solution would make a great answer.
    – RoG
    Oct 20, 2016 at 6:42
  • @Snaptastic see stackoverflow.com/a/12574407/673730 - A common mistake is forgetting to qualify the name :) Oct 20, 2016 at 19:59
  • 8
    They may be useful, just as are many answers to questions that are flagged as too general. Aug 16, 2019 at 19:07
  • 2
    I would like to see minimal reproducible example as something we ask of most new users , honestly. I don't mean anything by it, it is just - we can't expect people to follow the rules we don't inforce onto ourselves.
    – Danilo
    Sep 8, 2019 at 18:54

39 Answers 39

1
2
6

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.

3

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
3

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".
1
  • Actually the only difference between struct and class 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
2

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.

2

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.

1

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.

1
  • 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.
    – void
    Nov 22, 2020 at 11:53
0

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.

0

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(){}
0

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.

1
2

Not the answer you're looking for? Browse other questions tagged or ask your own question.