The C++ multiple definition error is a classic link-time error that occurs when a non-inline function body is defined in a header file and included across multiple .cpp files. Using real code and linker output reproduced on 2026-10-25 (KST) with g++ (Debian 14.2.0-19) 14.2.0, this post explains why the One Definition Rule (ODR) is violated and how to fix it with inline or a declaration/definition split.

Summary

This error happens when the linker finds two or more definitions of the same function because each .cpp file that includes a header containing a function body gets its own definition. You can fix it by marking the function in the header as inline, or by keeping only the declaration in the header and putting the single definition in one .cpp file.

What is the “multiple definition” error?

One-line answer: The multiple definition error is a link error emitted by the linker (ld/collect2) when combining object files (.o) that contain duplicate definitions of the same symbol, not a compile error.

Under the C++ One Definition Rule (ODR), only one definition of any variable, function, or class is allowed in any one translation unit, and one and only one definition of every non-inline function or variable that is odr-used is required in the entire program. Defining a non-inline function body inside a header included by two .cpp files violates this program-wide requirement.

Here are the three files that reproduce the error.

util.h:

#pragma once
int helper() { return 1; }

a.cpp:

#include "util.h"
int a() { return helper(); }

main.cpp:

#include "util.h"
int a();
int main() { return a() + helper(); }

Running g++ -std=c++17 a.cpp main.cpp -o odr_bad fails with exit status 1 and prints the following output (with temporary object file names replaced by ccXXXX):

/usr/bin/ld: /tmp/ccXXXX.o: in function `helper()':
main.cpp:(.text+0x0): multiple definition of `helper()'; /tmp/ccXXXX.o:a.cpp:(.text+0x0): first defined here
collect2: error: ld returned 1 exit status

Notice that the message comes from /usr/bin/ld and collect2 rather than the compiler parser. Compile-time errors look quite different; for an example of a compile error caused by preprocessor macro clashing, see What is the “expected unqualified-id before numeric constant” error? How to fix C++ macro name clashes.

Why does it happen even with header guards?

One-line answer: #pragma once and include guards only prevent a header from being included twice within a single translation unit (one .cpp file), so each separately compiled .cpp file still gets its own copy of the header’s contents.

Because each .cpp file is compiled independently, putting #pragma once at the top of util.h works only within one translation unit at a time:

  • When compiling a.cpp, util.h is included once, producing a definition of helper() in its object file.
  • When compiling main.cpp, util.h is also included once, producing another definition of helper() in its object file.
  • Each translation unit has only one definition so compilation succeeds, but the linker sees two definitions of helper() when combining the object files.

Each translation unit gets its own helper() definition when the header is included

How do you fix the “multiple definition” error?

One-line answer: Add inline to the function definition in the header, split the declaration in the header from a single definition in one .cpp file, or use static / an anonymous namespace if each file should have its own separate copy.

1. Mark the function in the header as inline

If you want to keep the function body in the header, add the inline specifier. Here is the fixed header util_inline.h:

#pragma once
inline int helper() { return 1; }

a_inline.cpp and main_inline.cpp are identical to a.cpp and main.cpp except that they include "util_inline.h". Building with g++ -std=c++17 a_inline.cpp main_inline.cpp -o odr_inline links with no error, and running ./odr_inline; echo $? prints:

2

The exit status 2 is the sum of a() returning 1 and helper() returning 1.

2. Keep the declaration in the header and put the definition in one .cpp file

A function declaration without a body is a declaration, not a definition. Keeping only the declaration in the header and placing the body in a single .cpp file ensures there is only one definition in the entire program (the snippet below is for illustration and was not run separately):

// util.h (illustrative snippet — not run)
#pragma once
int helper();

// util.cpp (illustrative snippet — not run)
#include "util.h"
int helper() { return 1; }

3. Use a static function or an anonymous namespace

Marking a function static or placing it inside an anonymous namespace in a header gives it internal linkage. Each .cpp file gets its own separate copy so there is no link clash, though there will be as many copies as there are files including the header (the snippet below is for illustration and was not run separately):

// util.h (illustrative snippet — not run)
#pragma once
static int helper() { return 1; }

When building with CMake, also check that a .cpp file is not added twice and that source files are listed once; for general CMake build configuration details, see AArch64 Cross-Compile with CMake: How to Use a Toolchain File.

Does inline mean “inline expansion”?

One-line answer: While the original intent of inline was a hint for inline substitution, since C++98 its primary meaning for functions is that “multiple definitions are permitted” across translation units.

According to the cppreference documentation on the inline specifier, compilers may inline functions not marked inline and may emit normal calls for functions marked inline. An inline function (or inline variable since C++17) with external linkage may have more than one definition in the program as long as each definition appears in a different translation unit and all definitions are identical (for example, defined in a header included in multiple source files).

C++17 extended inline to variables, removing the main obstacle to writing header-only libraries. If you want to inspect the exact code generated by the compiler, see What Is C++ Insights? How to See the Code Your Compiler Hides (Lambdas, Range-for).

What are the frequently asked questions?

One-line answer: Function and class templates, member functions defined inside a class body, and global variables in headers all follow the same ODR and inline rules.

Why can templates be defined in a header without inline?

Under the ODR, templated entities—just like class types, inline functions, and inline variables—are allowed to have more than one definition in a program as long as each definition appears in a different translation unit and the definitions consist of the same sequence of tokens.

Are member functions defined inside a class definition safe?

Yes. A function defined entirely inside a class definition is implicitly inline, and constexpr functions are also implicitly inline.

Does this error also happen with global variables?

Yes. Defining a non-inline variable in a header included by multiple .cpp files causes the same multiple definition error. Because extern without an initializer declares a variable without defining it, you can put an extern declaration in the header and define the variable in one .cpp file, or use a C++17 inline variable.

One-line answer: These related posts cover C++ compile errors, CMake build configuration, and inspecting compiler-generated code.

What are the sources?

One-line answer: This post is based on the cppreference pages for Definitions/ODR and the inline specifier, along with our GCC reproduction.