Fix 'Invalid Use of Incomplete Type' in C++ — Forward Declarations, sizeof, and the Pimpl Trap
A forward declaration lets you name a type, hold pointers and references to it, and declare functions that use it. It does not let you touch its members, measure it, derive from it, or destroy it through std::unique_ptr. This guide reads three GCC failures to the exact line that needed the definition, then fixes each one by moving the use, not by removing the forward declaration.
Written November 21, 2026 · Tested with GCC 13.3.0 · 18 min read
- The first failure: touching a type that has only been declared
- The second failure: the pimpl destructor, reported inside the library
- The third failure: a forward-declared base class
- The nearby case that is not this error: deleting an incomplete type
Written November 21, 2026
Tested with GCC 13.3.0
What this guide is
An incomplete type is a type that has been declared but not yet defined: a class type introduced by a forward declaration, an array of unknown bound, an array of incomplete elements, an enumeration type whose underlying type has not yet been determined, or void. Until the definition appears, the compiler knows the type's name and nothing else — not its size, not its members, not its base classes. Any use that needs one of those facts is rejected, and the rejection is this error. Uses that need none of them are fine, which is why the same forward declaration can be legal on one line and the cause of an error on the next: declaring a pointer or a reference to the type, and declaring a function that takes or returns it, need no size and no members; dereferencing it, reading a member, applying sizeof, defining an object of it, deriving from it, and deleting through it all do.
This guide works through three failures in the order they usually arrive. The first is the plain form, member access and sizeof on a forward-declared struct, where the diagnostic names the type and points back at the forward declaration. The second is the form that costs the most time in real code, the pimpl failure: a class holding a std::unique_ptr to a forward-declared implementation type, whose implicitly defaulted destructor is generated where that type is still incomplete, so the error surfaces inside the standard library header instead of in your code. The third is the base-class form, one line long. A fourth short program covers the trap next door: delete on an incomplete type is not this error, produces no error at all, and is worse for it.
Build every program in this guide with g++ -std=c++20 -g. Nothing here needs C++20 specifically; incomplete types, forward declarations, and std::unique_ptr behave the same way in the earlier standards that have them.
The first failure: touching a type that has only been declared
The smallest failing program forward-declares a struct and then uses it in the two most common ways:
#include <cstddef>
struct Config;
int read_id(Config* c) {
return c->id;
}
std::size_t config_size() {
return sizeof(Config);
}
int main() {
Config* c = nullptr;
return read_id(c) + static_cast<int>(config_size());
}
$ g++ -std=c++20 -g -o access access.cpp
access.cpp: In function ‘int read_id(Config*)’:
access.cpp:6:13: error: invalid use of incomplete type ‘struct Config’
6 | return c->id;
| ^~
access.cpp:3:8: note: forward declaration of ‘struct Config’
3 | struct Config;
| ^~~~~~
access.cpp: In function ‘std::size_t config_size()’:
access.cpp:10:12: error: invalid application of ‘sizeof’ to incomplete type ‘Config’
10 | return sizeof(Config);
| ^~~~~~~~~~~~~~
Read the first error in three parts. The error: line names the exact operation, member access through c->id at line 6, and the exact type, struct Config. The caret span sits under id, the member being requested: to resolve it the compiler would need the member list and the offset of id inside the object, and a forward declaration supplies neither. The note: line is the other half of the diagnosis and the line to look for in every variant of this error: it points at line 3, struct Config;, and labels it a forward declaration. Together the two lines say the whole story — at this point in the translation unit the only thing the compiler has ever seen for Config is that declaration, so the type is incomplete here, whatever any other file may define later.
The second error is the same cause with different wording, and the wording difference is worth noticing because searches land on both. sizeof needs the size, so GCC phrases it as invalid application of 'sizeof' to incomplete type 'Config' rather than invalid use. There is no forward-declaration note the second time; the compiler has already established which declaration it means. The operations in this family include: defining an object of the type, declaring a non-static data member of the type, a new expression, class member access, sizeof, alignof and typeid, pointer arithmetic on a pointer to the type, deriving from the type, and calling a function that returns or takes the type by value at the point of definition or call. Every one of them needs the size or the layout, and a forward declaration provides neither.
The fix is never to delete the forward declaration — it exists, usually, to keep an include out of a header. The fix is to move the use to a point where the definition is visible: define the function in the source file that includes the full definition, or include the defining header in the file that performs the use. A declaration of the function can stay where it was, because a declaration involving pointers to an incomplete type is legal; only the body had to move.
The second failure: the pimpl destructor, reported inside the library
The pimpl pattern stores the implementation behind a pointer so the header does not have to include the implementation's definition. With std::unique_ptr it fails in a specific, predictable place:
#include <memory>
struct Impl;
class Widget {
public:
Widget();
~Widget() = default;
private:
std::unique_ptr<Impl> impl_;
};
Widget::Widget() = default;
int main() {
Widget w;
return 0;
}
$ g++ -std=c++20 -g -o pimpl_bad pimpl_bad.cpp
In file included from /usr/include/c++/13/memory:78,
from pimpl_bad.cpp:1:
/usr/include/c++/13/bits/unique_ptr.h: In instantiation of ‘void std::default_delete<_Tp>::operator()(_Tp*) const [with _Tp = Impl]’:
/usr/include/c++/13/bits/unique_ptr.h:404:17: required from ‘std::unique_ptr<_Tp, _Dp>::~unique_ptr() [with _Tp = Impl; _Dp = std::default_delete<Impl>]’
pimpl_bad.cpp:13:1: required from here
/usr/include/c++/13/bits/unique_ptr.h:97:23: error: invalid application of ‘sizeof’ to incomplete type ‘Impl’
97 | static_assert(sizeof(_Tp)>0,
| ^~~~~~~~~~~
Nothing in this output points at a line that mentions Impl's members, because no such line exists. Read it from the bottom, as with a template error generally. The error: line is inside bits/unique_ptr.h at line 97, and it is not user code at all: it is a static_assert(sizeof(_Tp) > 0) inside std::default_delete<Impl>::operator(), the library's own guard against exactly this mistake. The chain above it explains how execution of the compile reached that guard. std::default_delete<Impl>::operator() was instantiated because std::unique_ptr<Impl>::~unique_ptr() calls it to destroy the managed object; the destructor was instantiated because something required it; and the last chain line, pimpl_bad.cpp:13:1: required from here, brings the chain back into your own file: line 13 is where the instantiation was required from, in a translation unit where the only declaration of Impl the compiler has seen is the forward declaration on line 3. The member responsible is the destructor defaulted inside the class on the ~Widget() = default; line: a destructor defined in the class body generates its call to ~unique_ptr<Impl>() in exactly that incomplete context.
That is the whole mechanism. std::unique_ptr may be constructed for an incomplete type — that is what makes the pimpl idiom possible with it at all — but if the default deleter is used, the type must be complete at every point where the deleter is invoked, and the deleter is invoked in unique_ptr's destructor, its move assignment operator, and its reset member function. A destructor of the enclosing class that is defaulted inside the class definition, or left implicit, is defined at a point where the compiler can see only the forward declaration, so the deleter is instantiated against an incomplete type and the library's sizeof guard fires. The constructor has the same exposure when it is defaulted in the same place and default-initializes the member, which is why both special members move together in the standard fix.
The fix is to declare, not define, the destructor (and the constructor, and the move operations if the class has them) in the header, and to define them in the source file at a point after the implementation type's full definition:
// In the header: declarations only.
class Widget {
public:
Widget();
~Widget();
private:
std::unique_ptr<Impl> impl_;
};
// In the source file, after struct Impl { ... }; is complete:
Widget::Widget() = default;
Widget::~Widget() = default;
= default is still correct in the source file; what changed is where the defaulting happens. At that point Impl is complete, sizeof(Impl) is a real number, the static_assert passes, and the generated destructor destroys the implementation object correctly. Deleting the = default in the header without declaring the destructor there does not work: an undeclared destructor is implicit, and an implicit destructor is generated in exactly the same incomplete context.
The third failure: a forward-declared base class
Deriving from a type needs its layout, because the derived object contains the base subobject. The diagnostic is the shortest of the three:
struct Base;
struct Derived : Base {
int value;
};
int main() {
Derived d{42};
return d.value;
}
$ g++ -std=c++20 -g -o base base.cpp
base.cpp:3:18: error: invalid use of incomplete type ‘struct Base’
3 | struct Derived : Base {
| ^~~~
base.cpp:1:8: note: forward declaration of ‘struct Base’
1 | struct Base;
| ^~~~
The caret sits under Base in the base clause, and the note again points at the forward declaration on line 1. There is no workaround that keeps the derivation in this translation unit ahead of the definition: a pointer to a base, a reference to a base, and a function declaration mentioning a base are all fine while it is incomplete, but a base class in a class definition is on the list of uses that require completeness, alongside defining an object of the type and declaring a data member of it. Include the header that defines the base before the derived class, or move the derived class definition into a file that does. In practice this form most often means an include was removed or reordered, not that the design changed: the base's header used to arrive transitively through another include, and stopped arriving.
The nearby case that is not this error: deleting an incomplete type
It is natural to expect delete on a pointer to an incomplete type to produce the same error. It does not:
struct Thing;
void destroy(Thing* t) {
delete t;
}
int main() {
destroy(nullptr);
return 0;
}
$ g++ -std=c++20 -g -o delete delete.cpp
delete.cpp: In function ‘void destroy(Thing*)’:
delete.cpp:4:5: warning: possible problem detected in invocation of ‘operator delete’ [-Wdelete-incomplete]
4 | delete t;
| ^~~~~~~~
delete.cpp:3:21: warning: ‘t’ has incomplete type
3 | void destroy(Thing* t) {
| ~~~~~~~^
delete.cpp:1:8: note: forward declaration of ‘struct Thing’
1 | struct Thing;
| ^~~~~
delete.cpp:4:5: note: neither the destructor nor the class-specific ‘operator delete’ will be called, even if they are declared when the class is defined
4 | delete t;
| ^~~~~~~~
The program compiles. The last note states the consequence exactly: neither the destructor nor a class-specific operator delete will be called, even if they are declared when the class is defined. Calling delete on an incomplete type is undefined behavior if the complete type has a nontrivial destructor or a deallocation function, precisely because the compiler has no way of knowing whether such functions exist and must be invoked; std::default_delete's own documentation makes the same point, and its operator() requires the type to be complete at the point it is called, which implementations guard with a static_assert — the guard seen firing in the pimpl failure above. So the absence of the error here is not permission. Treat -Wdelete-incomplete as an error in practice, and apply the same fix as everywhere else in this guide: perform the deletion where the type is complete. This contrast is also a diagnostic tool: if a build log shows only this warning for a type you expected to be incomplete-checked, the use that needs completeness is a raw delete, not one of the checked operations.
The rule underneath all three errors
A class type is incomplete from its forward declaration until its definition is seen in the same translation unit, and it is the same type at both points — completing it later in the file makes the later uses legal without changing anything about the earlier declarations. The contexts that require completeness are the ones that need the size or the layout: defining or calling a function with the type as a by-value argument or return, defining an object of it, declaring a non-static data member of it, a new expression, member access, conversion, sizeof, alignof and typeid, pointer arithmetic, defining a class derived from it, assignment, and an exception handler for it. Everything else — pointers, references, declarations, and, with the destructor caveat above, a std::unique_ptr member — works with the incomplete type, and that asymmetry is the entire value of a forward declaration.
So every instance of this error has the same shape: a use from the completeness list, at a point in the file above the definition, or in a file that never includes the definition. The diagnostic always contains the two coordinates needed to fix it — the line of the use in the error: line, and the line of the forward declaration in the note: line. The fix is always one of three moves: include the defining header before the use, move the use into a file or a position after the definition, or, for the generated-destructor case, move the definition of the special member to after the definition while leaving its declaration in the header. No instance of this error is fixed by changing the type, adding a cast, or removing the forward declaration that other declarations in the header legitimately depend on.
The fixed program: all three uses after the definitions
The fixed program keeps the same three shapes and performs each use only where the type is complete. Config is defined before read_id and config_size use it. Widget declares its constructor and destructor and defines both after Impl is complete, with the std::unique_ptr<Impl> member unchanged. Derived is defined after Base:
#include <cstddef>
#include <iostream>
#include <memory>
// Fix 1: complete the type before any use that needs its size or members.
struct Config {
int id;
};
int read_id(Config* c) {
return c->id;
}
std::size_t config_size() {
return sizeof(Config);
}
// Fix 2: the pimpl destructor is only declared in the header-visible
// part; it is defined after Impl is complete.
struct Impl {
int answer;
};
class Widget {
public:
Widget();
~Widget();
int answer() const;
private:
std::unique_ptr<Impl> impl_;
};
Widget::Widget() : impl_(std::make_unique<Impl>(Impl{42})) {}
Widget::~Widget() = default;
int Widget::answer() const { return impl_->answer; }
// Fix 3: complete the base class before deriving from it.
struct Base {
int base_value;
};
struct Derived : Base {
int value;
};
int main() {
Config c{7};
std::cout << "read_id = " << read_id(&c) << '\n';
std::cout << "config_size > 0 = " << (config_size() > 0) << '\n';
Widget w;
std::cout << "widget answer = " << w.answer() << '\n';
Derived d{{1}, 42};
std::cout << "derived value = " << d.value << '\n';
return 0;
}
$ g++ -std=c++20 -g -o fixed fixed.cpp
$ ./fixed
read_id = 7
config_size > 0 = 1
widget answer = 42
derived value = 42
No forward declaration was removed to get here. In a real header the forward declarations stay, the declarations that depend on them stay, and only the definitions and the bodies move to the side of the file boundary where the complete types are visible — which is the arrangement the forward declarations were introduced to make possible.
The fixes, ranked
Move the use after the definition, or include the definition before the use. Ranked first because it is what both coordinates in the diagnostic directly support: the error: line is the use, the note: line is the declaration that was all the compiler had, and putting the definition between them removes the failure without weakening the include structure the forward declaration was protecting, beyond the one file that genuinely needs the definition.
Declare the special members in the header and define them where the pointee is complete. For the pimpl form specifically: destructor, constructor, and any move operations are declared in the class and defaulted or defined in the source file after the implementation type's definition. This is the only fix for that form; including the implementation header in the public header also compiles, and defeats the reason the pimpl exists.
Check for a lost transitive include, when the code compiled before. The base-class and member-access forms in previously working code usually mean the defining header used to arrive through another header that no longer includes it. Include the defining header directly in the file that uses the type rather than restoring the transitive chain, so the dependency is stated where it is used.
Treat a delete-incomplete warning as this error's sibling, not as a pass. A raw delete on an incomplete type compiles with -Wdelete-incomplete and undefined behavior behind it. Move the deletion to where the type is complete, the same move as the first fix, and consider building with that warning promoted to an error so the case cannot slip through as a warning among warnings.
Which fix for which cause
| What the diagnostic shows | Cause | Fix |
|---|---|---|
| Error at a member access, note points at a forward declaration | Member list not visible at the use | Move the body after the definition, or include it |
Error: invalid application of sizeof to the type |
Size not known at the use | Same move: define first, measure after |
Error inside unique_ptr.h, a sizeof assert in default_delete |
Destructor defaulted where the pointee is incomplete | Declare in header, define after the pointee |
| Error at a base clause naming the base type | Base layout not visible at the derivation | Include the base definition before the derived class |
Only a -Wdelete-incomplete warning, no error |
Raw delete on an incomplete type |
Move the delete after the definition |
| Error in code that compiled before, no local edit | A transitive include stopped arriving | Include the defining header directly |
Checklist
- Read the
note:line before changing anything: it names the forward declaration, which confirms the type is incomplete at the use rather than undefined or misspelled — a misspelled type produces a different error entirely. - Classify the use against the completeness list: member access,
sizeof, object or member definition,new, derivation, pointer arithmetic, and by-value function definition or call all require the definition to be visible first. - If the error is reported inside a library header, follow the
required from herechain to the last line in your own file; that line, not the library line, is the one to move. - For a
std::unique_ptrmember, check where the enclosing destructor, constructor, and move operations are defined, not just declared; an implicit or in-class-defaulted definition is in the incomplete context even when no destructor line appears in the header at all. - Do not fix the pimpl form by including the implementation header in the public header unless the pimpl itself is being retired; the declare-here, define-there split is the fix the pattern expects.
- After the move, check the whole file for the same type: a second use above the definition produces a second error of the same kind, and fixing only the first reported line leaves the build failing at the next one.
- Grep the build log for
delete-incompleteafter the errors are gone; the warning form does not stop the build and is easy to miss once the errors that brought you to the log are fixed.
Related guides on this site
- Fix an Undefined Reference to a Vtable — a Missing Virtual Function Definition — the link-time counterpart: there the class is complete everywhere and a declared function is never defined; here the definition of the type itself has not been seen at the point of use.
- Fix a Template Undefined Reference — the Definition Belongs in the Header — the opposite placement rule for templates, where the definition must move toward the use rather than the use toward the definition; telling the two apart is the first step in either fix.
- Fix Multiple Definition Errors — Inline, the One Definition Rule, and Header Definitions — what goes wrong at the other extreme, when a definition is visible in too many translation units instead of too few.
- Fix a Dangling std::string_view — Lifetime Rules for Views and References to Temporaries — another case where a type that only refers to data, there a view and here a forward declaration, is safe exactly as long as nothing asks it for the thing it does not own or know.
Sources
- cppreference, Type: incomplete type — for the kinds of incomplete type, for the full list of contexts that require a type to be complete, and for a class type being the same type before and after it is completed in a translation unit.
- cppreference, Class declaration: forward declaration — for a forward declaration declaring a class type that has incomplete type until its definition appears, and for pointers and references making it possible to reduce include dependencies.
- cppreference, std::unique_ptr — for a unique_ptr being constructible for an incomplete type to facilitate the pImpl idiom, and for the type needing to be complete, with the default deleter, at the points where the deleter is invoked: the destructor, move assignment operator, and reset member function.
- cppreference, std::default_delete — for the deleter calling delete on its argument, for its operator() being ill-formed for an incomplete type, and for delete on an incomplete type being undefined behavior when the complete type has a nontrivial destructor or a deallocation function.
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.