Why does linking a C++ program fail with an undefined vtable for Body when Body's constructor and other members compile fine?
answer
- the vtable is emitted in one place
- first non-inline, non-pure virtual
- declared but never defined
- or its .cpp never linked
basics
~20 sUnder the Itanium C++ ABI, Body's vtable is emitted only in the translation unit that defines its key function, the first non-inline, non-pure virtual function. If that function is never defined or its file is not linked, no vtable exists.
solid answer
~50 sIn the **Itanium C++ ABI** (GCC, and Clang outside Windows), a class's vtable and RTTI are emitted in exactly one translation unit: the one that defines its **key function**, the first virtual function declared in the class that is neither inline nor pure. Every constructor of `Body` stores the vtable's address in the vptr, so it references the vtable symbol. If the key function is **declared but never defined**, or defined in a `.cpp` file that is not compiled into the target, nobody emits the vtable and the link fails. Apple's linker adds a note that says so: a missing vtable usually means the first non-inline virtual member function has no definition. The compiler cannot catch it because the standard makes an undefined, non-pure virtual function ill-formed with **no diagnostic required**. Fix it by defining the function, adding its file to the target, or making it pure.
code
cpp · 11 lines// body.h would normally hold this class; body.cpp was supposed to define step().
struct Body {
virtual ~Body() = default;
virtual void step(float dt); // key function: first non-inline, non-pure virtual
virtual float energy() const { return 0.0f; }
};
int main() {
Body b; // needs the vtable for Body
return static_cast<int>(b.energy());
}go deeper
Know that this link error means a virtual function was declared but its definition is missing or not linked, and look for it first.
Explain the key function rule: the first non-inline, non-pure virtual function's defining file emits the vtable, so its absence leaves no vtable at all.
Diagnose it quickly in a real build: missing source in the target, mismatched definition, the companion typeinfo error, and why no compiler warning fires.
Set the convention for widely used polymorphic classes, such as an out-of-line anchor destructor, to keep vtable emission predictable and builds lean.
## The symptom A physics library declares its body class in a header: ```cpp struct Body { virtual ~Body() = default; virtual void step(float dt); // declared, defined in body.cpp virtual float energy() const { return 0.0f; } }; ``` Every file that uses `Body` compiles. Then the link fails, naming not `step` but the table. With Apple clang 21 the linker printed: ```plaintext Undefined symbols for architecture arm64: "vtable for Body", referenced from: Body::Body() in key-824d9d.o NOTE: a missing vtable usually means the first non-inline virtual member function has no definition. ``` GNU ld and lld report the same missing symbol in their own words. The error points at the constructor because constructors are what store the vtable's address in each new object's vptr. ## Why the vtable has a single home A vtable is a data object with a definition, and the program needs one copy. The **Itanium C++ ABI** picks the translation unit to emit it in with the **key function** rule: - the key function is the **first virtual function declared in the class that is neither pure nor defined inline** in the class (a function defined in the class body is implicitly inline); - the translation unit that **defines** the key function emits the vtable and the class's RTTI as ordinary strong symbols; - every other translation unit only references them. For `Body`, the destructor is defaulted inline and `energy` is defined in the class, so `step` is the key function, and `body.cpp`, which should define it, is the vtable's only home. ## The usual causes 1. **The function was declared but never defined:** a new virtual function was added to the header and the definition was forgotten. 2. **The definition is in a file the target does not build:** `body.cpp` exists but is missing from the target's source list, so its object file is never linked. 3. **The definition does not match the declaration:** it is in a different namespace or class, so it defines another function and the key function stays undefined. 4. **A typeinfo error with the same cause:** an undefined typeinfo for `Body` comes from the same missing translation unit, because the RTTI is emitted with the vtable. ## Classes without a key function If every virtual function is pure or defined inline, there is no key function. The compiler then emits the vtable in **every** translation unit that needs it, as a weak or COMDAT symbol, and the linker keeps one copy. That always links, at the cost of duplicated work and larger object files, which is why some codebases deliberately declare a non-inline virtual destructor and define it in the `.cpp` file as an **anchor** for the vtable. ## Why the compiler cannot warn The standard says a virtual function declared in a class shall be defined, or declared pure, or both, and that **no diagnostic is required**. Each translation unit sees only a declaration, which is legal on its own; only the linker sees that no definition exists anywhere. Compilers following the MSVC ABI do not use the key-function rule, so the same mistake is reported differently there, but the cause is still a declared virtual function with no definition. ## Checklist for the error | Check | How | |---|---| | Is the first non-inline, non-pure virtual function defined anywhere? | search for `Body::step` definitions | | Is that file part of the target being linked? | inspect the target's source list | | Does the definition's signature match the declaration exactly? | compare namespace, class, parameters and `const` | | Should the function be pure instead? | add `= 0` if `Body` is meant to be abstract | ## Confirming it with nm The symbol table answers the question directly. `nm -C` on each object file lists `vtable for Body` with a defined-symbol letter in the one file that emits it, and with `U` (undefined, merely referenced) everywhere else. Compiling the broken example and running `nm -C` on its object file printed only `U vtable for Body`: a reference with no definition anywhere. Running it over every object file in the failing link and finding no defining entry confirms the key function's file is missing; finding a defining entry in a file that is not on the link line confirms the build-configuration cause.
- Why do some codebases define an empty virtual destructor in the .cpp file instead of defaulting it in the class?To give the class a key function. An out-of-line virtual destructor defined in one `.cpp` file anchors the vtable and RTTI in that translation unit, so other files only reference them instead of each emitting a weak copy for the linker to merge. It reduces object-file size and link work for widely included classes.
- What changes if every virtual function of Body is defined inline in the header?Body then has no key function, so every translation unit that needs the vtable emits it as a weak or COMDAT symbol and the linker keeps one. The undefined-vtable error cannot occur, but the table and RTTI are compiled repeatedly; the program still has one vtable after linking.
- An undefined vtable means the class forgot to declare a virtual destructor.
- The compiler should have rejected the missing definition at compile time.
- Every translation unit that includes the header emits its own strong vtable.
- The key function is always the class's destructor.