C++

Fix "Multiple Definition" Link Errors — Header Definitions and inline

Put a function definition in a header, include that header in two source files, and the program compiles cleanly and then refuses to link: multiple definition of the function, and of any variable the header defines alongside it. This guide builds that failure on purpose, reads each line of the linker output, and fixes it two ways — inline, and the older split of declaration in the header and one definition in a source file. A last pair of programs shows the fix that links but lies: static gives every file its own copy, so the counter one file increments is not the counter another file reads.

Written November 18, 2026 · Tested with GCC 13.3 · 9 min read

By the end of this guide
  • The broken header: compiles twice, links never
  • The rule underneath: one definition per program
  • Fix one: mark both definitions inline
  • Fix two: declare in the header, define once in a source file

What this guide is

A header is not a place where definitions are stored once. It is text that gets copied into every source file that includes it, and each of those source files is compiled on its own into a translation unit. A definition written in a header therefore exists once per translation unit, and for an ordinary function or variable the program is allowed exactly one definition in total. The examples here use C++17 and GCC 13.3, and every program is a small set of files: a header, a second source file named a.cpp, and a main.cpp. The same header and the same two callers run through the whole guide; only the header changes.

The header defines a function and a variable:

C++
// greet.h
#pragma once
#include <string>
std::string greeting() { return "hello"; }
int counter = 0;

Two source files include it. The first increments the counter and prints:

C++
// a.cpp
#include "greet.h"
#include <iostream>
void print_a() { ++counter; std::cout << "a: " << greeting() << " counter=" << counter << "\n"; }

The second calls the first and prints its own reading of the same counter:

C++
// main.cpp
#include "greet.h"
#include <iostream>
void print_a();
int main() {
    print_a();
    std::cout << "main: " << greeting() << " counter=" << counter << "\n";
    return 0;
}

Compile each file on its own and both compile without a complaint, because each translation unit on its own is legal. The failure arrives when the two object files are linked:

Terminal
$ g++ -std=c++17 -Wall -Wextra -c a.cpp -o a.o
$ g++ -std=c++17 -Wall -Wextra -c main.cpp -o main.o
$ g++ a.o main.o -o prog
/usr/bin/ld: main.o: in function `greeting[abi:cxx11]()':
main.cpp:(.text+0x0): multiple definition of `greeting[abi:cxx11]()'; a.o:a.cpp:(.text+0x0): first defined here
/usr/bin/ld: main.o:(.bss+0x0): multiple definition of `counter'; a.o:(.bss+0x0): first defined here
collect2: error: ld returned 1 exit status

Read the output as a list of collisions, not as noise. There are two errors, one per entity the header defined. The function error names greeting — the bracketed text after it is part of the symbol name the linker works with for a function that returns a std::string — and it says where each copy came from: one in main.o, first defined in a.o. The variable error is shorter because a variable's symbol is just its name: counter, defined in both object files. Nothing in the output points at a line inside the header, and that absence is the first clue about the cause. The header itself is not wrong in either file. The program as a whole has each definition twice.

Include guards and #pragma once do not touch this problem. A guard stops a header from being pasted twice into one translation unit. This error is about the header being pasted once each into two translation units, which is exactly what including a header is for.

The rule underneath: one definition per program

The One Definition Rule allows only one definition of any variable or function in a single translation unit, and it requires one and only one definition of every non-inline function or variable that the program uses to appear in the entire program. The broken header breaks the second half of that rule twice over: greeting is defined in two translation units, and so is counter.

The rule has a short list of exceptions — entities that may be defined in more than one translation unit, as long as every definition is identical and each appears in a different translation unit. Class types are on that list, which is why a struct or class definition can live in a header at all. Templates are on it. And inline functions and inline variables are on it, which is the fix the next section uses. Everything else defined in a header is a link error waiting for a second file to include it.

Fix one: mark both definitions inline

Adding one word to each definition in the header puts both entities on the exception list:

C++
// greet.h
#pragma once
#include <string>
inline std::string greeting() { return "hello"; }
inline int counter = 0;

The same two source files, unchanged, now build and run:

Terminal
$ g++ -std=c++17 -Wall -Wextra -c a.cpp -o a.o
$ g++ -std=c++17 -Wall -Wextra -c main.cpp -o main.o
$ g++ a.o main.o -o prog
$ ./prog
a: hello counter=1
main: hello counter=1

Two details in that output carry the point. The link succeeds, which is the visible change. And main prints counter=1, the value print_a left behind, which proves the two files are reading and writing one shared variable, not two copies that happen to hold the same starting value. An inline variable has the same address in every translation unit, and an inline function's local static objects are shared the same way.

The word inline here is a statement about definitions, not about speed. Its original job was to hint that calls to the function could be substituted with the function body, but compilers make that choice on their own for any function, marked or not. Since C++98 the keyword's binding meaning for functions has been that multiple definitions are permitted, and C++17 extended the same meaning to variables — before C++17 there was no inline variable, which is why older code could not fix the variable half of this error in the header at all. An inline entity must be declared inline in every translation unit that defines it, and all of its definitions must be identical; a header is what makes both of those easy to keep true, because every translation unit reads the same text.

Fix two: declare in the header, define once in a source file

The older fix keeps the header but takes the definitions out of it. The header declares the function and declares the variable with extern, which promises that a definition exists somewhere without providing one:

C++
// greet.h
#pragma once
#include <string>
std::string greeting();
extern int counter;

One source file, added to the project, holds both definitions and is the only file that does:

C++
// greet.cpp
#include "greet.h"
std::string greeting() { return "hello"; }
int counter = 0;

Built with the same two callers, the program prints the same two lines as the inline fix:

Terminal
$ g++ -std=c++17 -Wall -Wextra greet.cpp a.cpp main.cpp -o prog
$ ./prog
a: hello counter=1
main: hello counter=1

This is the right shape when the definition is large, when it changes often enough that recompiling every includer is a real cost, or when the project still targets a standard older than C++17 and the variable therefore cannot be inline. It costs one more file to keep track of, and the variable's initializer lives in that file rather than next to its declaration. The inline form is the right shape for the small, stable helpers that headers usually hold, and it is the only one of the two that works for a header-only library, where there is no extra source file a user could be asked to compile.

Trap
There is a third edit that also makes the link error disappear, and it is the wrong one. Mark the variable static and give the function its correct inline form:
C++
// greet.h
#pragma once
#include <string>
inline std::string greeting() { return "hello"; }
static int counter = 0;

The program builds, and it runs:

Terminal
$ g++ -std=c++17 -Wall -Wextra a.cpp main.cpp -o prog
$ ./prog
a: hello counter=1
main: hello counter=0

The second line is the failure. A namespace-scope static variable has internal linkage, which means each translation unit gets an object of its own that merely shares a name with the others. print_a incremented the counter that belongs to a.cpp; main read the separate counter that belongs to main.cpp, which nobody had touched. No diagnostic reports this, because nothing is illegal — the code asked for two variables and got them. A plain namespace-scope const variable in a header lands in the same place by a different route: it has internal linkage by default, so each translation unit holds its own copy. For a constant whose value is all that is ever read, the copies are harmless. The moment code compares addresses, registers the variable somewhere central, or expects a write in one file to be visible in another, the copies stop being harmless and the bug is silent.

Use static in a header only when a private copy per file is what the code actually wants, for example a small lookup table that each file reads and none modifies. For a shared counter, a shared cache, or any state that is supposed to be the program's one copy, static is a link fix that converts a loud error into a quiet wrong answer.

The case that never needed fixing: functions defined inside a class

One common header pattern looks like the broken header and is not. A member function defined inside its class definition is implicitly inline, so it may appear in every translation unit that includes the class:

C++
// widget.h
#pragma once
#include <string>
struct Widget {
    std::string name() const { return "widget"; }
    int size() const { return 42; }
};

Two files include it, each builds a Widget, and the program links and runs:

C++
// a.cpp
#include "widget.h"
#include <iostream>
void print_a() { Widget w; std::cout << "a: " << w.name() << " " << w.size() << "\n"; }
C++
// main.cpp
#include "widget.h"
#include <iostream>
void print_a();
int main() {
    print_a();
    Widget w;
    std::cout << "main: " << w.name() << " " << w.size() << "\n";
    return 0;
}
Terminal
$ g++ -std=c++17 -Wall -Wextra a.cpp main.cpp -o prog
$ ./prog
a: widget 42
main: widget 42

The same implicit-inline rule covers a function declared constexpr, and static data members declared constexpr are implicitly inline variables. A non-constexpr static data member declared inside a class is only a declaration; before C++17 it needed one definition in a source file, and since C++17 declaring it inline static inside the class provides that definition in the header.

Which fix for which header

What the header holds Fix Why
A small function definition used by several files inline on the definition Multiple identical definitions are permitted, and a header-only library stays header-only
A variable that several files must share inline on the definition (C++17 or later) One object, one address, in every translation unit
A large or fast-changing function definition Declaration in the header, definition in one source file Only that one file recompiles when the definition changes
A variable on a standard older than C++17 extern declaration in the header, definition in one source file Inline variables do not exist before C++17
A table or buffer each file should own privately static in the header Internal linkage gives each translation unit its own copy, on purpose
A member function defined inside the class Nothing It is implicitly inline already

Checklist

  • Before adding a second file that includes a header, search the header for definitions: a function body, or a variable with an initializer and no extern. Each one is a future link error.
  • Before reaching for static to silence a multiple-definition error, decide whether the program wants one shared object or one copy per file. If it wants one shared object, static is the bug, not the fix.
  • Before marking a function inline, confirm the definition is identical in every translation unit — a shared header is what normally guarantees that — and that it is declared inline everywhere it is defined.
  • Before defining a variable in a header, check the standard the project builds with. Inline variables need C++17; on anything older, the definition belongs in a source file.
  • Before blaming a header for a link error, read which symbols the linker named. It lists exactly the entities that were defined more than once, and a symbol it does not name is not part of this problem.

Sources

  • cppreference, inline specifier — what inline declares for functions and, since C++17, for variables: more than one identical definition is permitted, it must be declared inline in every translation unit, and an inline variable has the same address everywhere.
  • cppreference, Definitions and ODR — the One Definition Rule, the entities that may be defined in more than one translation unit, and which declarations are not definitions, including an extern declaration without an initializer.

Keep Exploring