Fix "Undefined Reference to Vtable" — the Missing Virtual Function
Most linker errors name a function. This one names a table. A class declares a virtual function, no file ever defines it, and the link fails with an undefined reference to the vtable for the whole class — even in a program that never calls the missing function. This guide builds that failure on purpose, reads the one-line error, and traces it to the rule that decides where a vtable is generated: in the translation unit that defines the class's first non-inline virtual function. Three fixes follow, each for a different intent, plus the symbol check that confirms the diagnosis before any code changes and the variant where the missing function is the destructor.
Written November 18, 2026 · Tested with GCC 13.3 · 6 min read
- The broken class: every file compiles, the link fails
- Why the error names a table instead of the function
- Confirm the diagnosis with nm before changing anything
- Fix one: define the missing function
What this guide is
A missing ordinary function produces a linker error that names the function. A missing virtual function can produce a stranger one: the error names the class's virtual table, a compiler-generated data structure the source never mentions, and the function that is actually missing appears nowhere in the output. The examples here use C++17 and GCC 13.3. The Widget examples thread the same three files — a header named widget.h, a source file named widget.cpp, and a main.cpp — through the guide; only the definitions change. Two smaller examples near the end use files of their own. The rule that explains the error is not a rule of the C++ language itself. It is a rule of the Itanium C++ ABI, the object-file convention GCC and Clang follow on Linux and most other non-Windows platforms, and this guide states it as exactly that.
The broken class: every file compiles, the link fails
The header declares a class with two virtual functions and defines neither of them:
// widget.h
#pragma once
struct Widget {
virtual void draw();
virtual void resize();
};
The source file defines one of the two. resize gets a body. draw is never defined anywhere in the program — not in this file, not in any other:
// widget.cpp
#include "widget.h"
#include <iostream>
void Widget::resize() { std::cout << "resized\n"; }
The program constructs a Widget and calls the function that does exist. It never calls draw:
// main.cpp
#include "widget.h"
int main() {
Widget w;
w.resize();
return 0;
}
Compile each file on its own and both compile without a complaint. The failure arrives when the two object files are linked:
$ g++ -std=c++17 -Wall -Wextra -c widget.cpp -o widget.o
$ g++ -std=c++17 -Wall -Wextra -c main.cpp -o main.o
$ g++ widget.o main.o -o prog
/usr/bin/ld: main.o: warning: relocation against `_ZTV6Widget' in read-only section `.text'
/usr/bin/ld: main.o: in function `main':
main.cpp:(.text+0x1e): undefined reference to `vtable for Widget'
/usr/bin/ld: warning: creating DT_TEXTREL in a PIE
collect2: error: ld returned 1 exit status
Read the middle line and ignore the two warnings around it; they are side effects of the same missing symbol, not separate problems. The error says that main.o refers to a symbol called vtable for Widget (the linker works with the mangled spelling _ZTV6Widget; the demangled reading is the one that matters) and that no object file supplies it. It does not say that draw is missing, even though that is the whole problem. And it fires even though main never calls draw — constructing the object is enough, because construction is what needs the table.
Why the error names a table instead of the function
Every object of a class with virtual functions carries a hidden pointer to that class's virtual table, and the table holds the addresses of the virtual functions, one slot per function. The constructor sets the pointer, so any file that constructs a Widget needs the table itself to exist somewhere in the program. One copy is enough, and the ABI fixes exactly where that copy is generated.
The ABI calls the deciding function the key function: the first non-pure virtual function of the class that is not defined inline in the class definition. The virtual table for the class is emitted in the translation unit that contains the definition of the key function, and nowhere else. In Widget, the first virtual is draw, declared in the header and defined in no file at all. draw is the key function, its defining translation unit does not exist, and so no object file ever emits the table. resize being properly defined does not help, because the table does not travel with just any virtual function. It travels with the first one.
Two consequences follow, and both match what the error shows. First, the missing symbol is the table, not the function: nothing in main.o calls Widget::draw directly, so the linker has no occasion to complain about that name, while the constructor's need for the table is a direct reference that must be satisfied. Second, calling the missing function is not what triggers the failure. A program that constructs the object and calls only defined functions still fails, as the example above does, because the reference comes from construction itself.
Confirm the diagnosis with nm before changing anything
The object files state the problem directly. nm lists the symbols each one defines and the symbols it leaves undefined, marked U:
$ nm -C main.o | grep vtable
U vtable for Widget
$ nm -C widget.o | grep vtable
The first command shows main.o holding an undefined reference to the table. The second prints nothing at all: widget.o, the file that was supposed to supply the table, contains no vtable symbol in either column. That pair of results is the whole diagnosis. When a vtable error appears, run the same check on the object files of the class and its users. A U line in the users and silence in the class's own object file means the key function is missing. A definition of the table in the class's object file, marked V because the symbol is weak, means the table exists and the problem sits somewhere else — an object file missing from the link line, for example, which is a build error and not a code error at all.
Fix one: define the missing function
The direct fix is the one the diagnosis points at. draw is declared, so give it a definition in the class's source file, alongside resize:
// widget.cpp
#include "widget.h"
#include <iostream>
void Widget::draw() { std::cout << "drawn\n"; }
void Widget::resize() { std::cout << "resized\n"; }
With the key function defined, widget.o now emits the table — the same nm check that printed nothing before now shows the weak definition — and the program links. This version of main calls both functions, to show the previously missing one working:
// main.cpp
#include "widget.h"
int main() {
Widget w;
w.draw();
w.resize();
return 0;
}
$ g++ -std=c++17 -Wall -Wextra widget.cpp main.cpp -o prog
$ ./prog
drawn
resized
$ g++ -std=c++17 -Wall -Wextra -c widget.cpp -o widget.o
$ nm -C widget.o | grep "vtable for Widget"
0000000000000000 V vtable for Widget
This is the right fix when the function is a real part of the class that was simply never written, or when its definition was lost in an edit — a body deleted, a source file dropped from the build, a definition left behind in a rename. In each of those cases the class design already says the function exists. The fix restores the definition rather than changing the design.
The destructor variant: the error names the destructor instead
The key function is not always an ordinary member. When the first non-inline virtual is the destructor, the same missing definition produces a different pair of errors. This example declares a virtual destructor and never defines it, while the other virtual is defined inline in the header:
// base.h
#pragma once
struct Base {
virtual ~Base();
virtual void draw() {}
};
struct Button : Base {};
// main.cpp
#include "base.h"
int main() {
Button b;
return 0;
}
$ g++ -std=c++17 -Wall -Wextra -c main.cpp -o main.o
$ g++ main.o -o prog
/usr/bin/ld: main.o: in function `Button::~Button()':
main.cpp:(.text._ZN6ButtonD2Ev[_ZN6ButtonD5Ev]+0x26): undefined reference to `Base::~Base()'
/usr/bin/ld: main.o:(.data.rel.ro._ZTI6Button[_ZTI6Button]+0x10): undefined reference to `typeinfo for Base'
collect2: error: ld returned 1 exit status
Two undefined names, one root cause. Destroying a Button runs the base destructor, so the missing Base::~Base() is named directly this time. The typeinfo for Base line is the companion failure: under the ABI, the run-time type information for a class is emitted in the same object file as its virtual table, and the table is again waiting on the key function — here, the destructor. The fix is to define the destructor, in a source file of its own or with = default written as an out-of-line definition:
// base.cpp
#include "base.h"
Base::~Base() = default;
$ g++ -std=c++17 -Wall -Wextra base.cpp main.cpp -o prog
$ ./prog
The program links and runs, printing nothing. A virtual destructor cannot be left as a bare declaration either — every derived destructor calls it, so its missing definition surfaces as soon as a derived object is destroyed — and this variant is the common way the vtable family of errors appears in real code, because the destructor is declared first in most base classes and its definition is the easiest one to lose when a class is moved between files.
Fix two: make the function pure virtual
Sometimes the missing definition is not an accident. A base class may declare a function precisely because every derived class must supply it, and the base has no sensible body of its own. That intent has a spelling: declare the function pure virtual, and the class becomes abstract:
// widget.h
#pragma once
struct Widget {
virtual void draw() = 0;
virtual void resize();
};
A pure virtual function is not a candidate for key function — the ABI's definition takes the first non-pure virtual — so the table's emission moves to resize, which is defined in widget.cpp as before, and the link succeeds with a derived class that supplies draw:
// main.cpp
#include "widget.h"
#include <iostream>
struct Button : Widget {
void draw() override { std::cout << "drawn\n"; }
};
int main() {
Button b;
b.draw();
b.resize();
return 0;
}
$ g++ -std=c++17 -Wall -Wextra widget.cpp main.cpp -o prog
$ ./prog
drawn
resized
The trade is explicit. An abstract class cannot be instantiated, so code that constructed the base directly stops compiling — which is a compile error with a clear message, caught at the point of misuse, instead of a link error at the end of the build:
$ g++ -std=c++17 -Wall -Wextra -c bad.cpp -o bad.o
bad.cpp: In function ‘int main()’:
bad.cpp:3:12: error: cannot declare variable ‘w’ to be of abstract type ‘Widget’
3 | Widget w;
| ^
In file included from bad.cpp:1:
widget.h:2:8: note: because the following virtual functions are pure within ‘Widget’:
2 | struct Widget {
| ^~~~~~
widget.h:3:18: note: ‘virtual void Widget::draw()’
3 | virtual void draw() = 0;
| ^~~~
Here bad.cpp is a small program whose only act is declaring Widget w; inside main. Choose this fix when the base class is a genuine interface. Do not choose it to silence the linker for a class that code legitimately constructs; that trades one missing definition for a class nothing can instantiate. One boundary case belongs to this fix: a destructor may be declared pure virtual, but it still needs a definition, because derived destructors call it. Pure is a statement about instantiation, not an exemption from defining the destructor.
Why header-only classes never produce this error
A class whose virtual functions are all defined inline in the header has no key function at all, and the ABI's fallback applies: the table is emitted in every translation unit that references it, as a weak symbol the linker merges into one. The same Widget, written header-only, links with no source file involved:
// widget.h
#pragma once
#include <iostream>
struct Widget {
virtual void draw() { std::cout << "drawn\n"; }
virtual void resize() { std::cout << "resized\n"; }
};
// main.cpp
#include "widget.h"
int main() {
Widget w;
w.draw();
w.resize();
return 0;
}
$ g++ -std=c++17 -Wall -Wextra main.cpp -o prog
$ ./prog
drawn
resized
This is the third fix, and it is a real one for small classes in headers by design. It is also the reason the vtable error surprises people: a class can work for months in a header, then gain a source file, a first out-of-line virtual, and a key function nobody knew it had — and the first declared-but-undefined virtual after that move breaks links in programs that never call it.
Which fix for which class
| Shape of the problem | Fix | Why |
|---|---|---|
| The function is part of the class and was never written, or its definition was lost in an edit | Define it in the class's source file | The key function now has a defining translation unit, which is where the table is emitted |
| The error names the destructor and the typeinfo instead of the vtable | Define the virtual destructor (an out-of-line = default is enough) |
The destructor is the key function; the type information is emitted in the same object as the table |
| The base class is an interface and should never be constructed directly | Make the function pure virtual and override it in each derived class | A pure virtual is never the key function, and the class becomes abstract on purpose |
| The class is small and lives in a header by design | Define the virtual functions inline in the class definition | With no key function, the table is emitted wherever it is referenced, as a weak symbol |
nm shows the table defined in the class's object file but the link still fails |
Fix the build, not the class — the object file is missing from the link | The code already supplies the table; the linker never sees the file that holds it |
Checklist
- Before hunting through the class for a typo, read the error for what it names. An undefined reference to the vtable means a missing definition of one specific function, and the linker is never going to name it for you.
- Before changing any code, run
nm -Con the class's object file and a user's object file. An undefined table in the user and no table symbol at all in the class's file confirms the missing key function. - Before picking a fix, find the key function: the first virtual in the class that is neither pure nor defined inline in the class definition. Its definition is the one to look for.
- Before assuming the missing function is an ordinary member, check the destructor. A declared, undefined virtual destructor is the same bug with a different error text.
- Before making a function pure virtual to clear the error, confirm nothing constructs the base class. The fix changes what the class is, not just where a table is emitted.
- Before adding the class's source file to a build as the fix, check whether it is already there. If
nmshows the table defined, the code is right and the link line is wrong.
Related guides on this site
- Fix "Multiple Definition" Link Errors — Header Definitions and inline — the opposite header failure: a definition the linker sees too many times, where this guide is about a table it never sees at all.
- Fix Template "Undefined Reference" — Why Template Definitions Cannot Hide in a .cpp — undefined references whose missing names are concrete template instantiations, traced to which file was supposed to generate them.
- C++ Classes and Objects — how a class is declared in a header and defined in a source file, the split whose virtual-function case this guide covers.
- C++ Functions: Parameters, Overloads, and Default Arguments — declarations and definitions of ordinary functions, whose linker errors name the function directly, unlike the vtable case.
Sources
- Itanium C++ ABI, Virtual Tables — the key function is the first non-pure virtual function not inline at the point of class definition; the virtual tables are emitted in the object for the translation unit containing the key function's definition, or in every referencing object when there is no key function; the type information for a class is emitted in the same object as its virtual tables.
- cppreference, Virtual functions — virtual functions support dynamic dispatch through a base pointer or reference, a derived destructor always overrides a virtual base destructor, and deleting a derived object through a base pointer whose destructor is not virtual is undefined behavior.
- cppreference, Abstract classes — a pure virtual function makes its class abstract, no objects of an abstract class can be created, and the definition of a pure virtual function may be provided and must be provided when the pure virtual is the destructor.
Keep Exploring
Seven tips and seven puzzles so far, each one a short runnable example with the fix explained.
Paste an AddressSanitizer, UBSan, or ThreadSanitizer report and get the bug, the file and line, and the fix \u2014 in plain language.
C++20 and C++23 features, migration paths, and measured trade-offs.
The full C++ hub \u2014 language basics, the standard library, coroutines, and measured comparisons.
Paste a [Service] section and get a plain-language verdict on every sandboxing setting it finds.