With GCC, how do you read a hundred-line error from calling std::sort on a std::list and find the line to fix?
answer
- the first error matters most
- the instantiation chain leads home
- the frame in your own file
- random-access versus bidirectional
- -Wfatal-errors, template-tree, concepts depth
basics
~20 sRead the first error, then follow its instantiation notes to the one frame in your own source: that is the call to fix. Here std::sort needs random-access iterators and std::list has bidirectional ones, so call the list's own sort() instead.
solid answer
~40 sA template error is reported where it breaks, deep inside the library, plus a chain of instantiation notes that connects that point to the line in your code that started it. So: start at the first error, ignore the later cascade, and find the frame whose file is yours. For `std::sort(lst.begin(), lst.end())` the library fails where it needs iterator arithmetic, because `std::sort` requires random-access iterators and `std::list` only has bidirectional ones; the fix is `lst.sort()`. GCC options help: `-Wfatal-errors` or `-fmax-errors=1` stop the cascade, `-ftemplate-backtrace-limit=` (default 10) controls how many notes print, `-fdiagnostics-show-template-tree` shows where two long types differ, and C++20 constrained algorithms like `std::ranges::sort` fail with a short concept message instead.
code
cpp · 7 lines#include <algorithm>
#include <list>
int main() {
std::list<int> latencies{30, 10, 20};
std::sort(latencies.begin(), latencies.end()); // needs random-access iterators
}go deeper
Start at the first error, find the line in your own file, and ask what the template needed from your types.
Explain why the error lands inside the library, how the instantiation chain links it to your call, and which GCC flags trim the output.
Use constrained algorithms and your own concepts so errors surface at call sites, and know the template-tree and concepts-depth options.
Weigh designing library interfaces with explicit constraints so that users of your templates get short, actionable errors.
## Why template errors are long A function template such as `std::sort` is only checked fully when it is **instantiated** with your types. If your types do not support an operation the template uses, the error happens inside the library's implementation, several calls below the line you wrote. The compiler therefore reports: - the **error itself**, at a line inside a library header - a chain of **instantiation notes**, one per template that was being instantiated, connecting that line to the one in your source file that triggered it - often **candidate notes** listing overloads of an operator it tried - then **more errors**, because one failure usually breaks several later statements in the same template ## A reading procedure 1. **Start at the first error.** Later errors are frequently consequences of it. 2. **Read the error's subject, not its location.** "Invalid operands to binary `-`" with two iterator types already says the iterator cannot do arithmetic. 3. **Walk the instantiation chain to your own file.** The frame whose path is in your project, not under the compiler's include directory, is the call you control. 4. **Ask what the template requires of your types** at that call: an iterator category, a comparison, a copyable element. 5. **Fix at your call site**, not in the library. For the example below, Apple clang 21 with libc++ printed 114 lines. Its first error, inside libc++'s heap code, was: ```plaintext error: invalid operands to binary expression ('std::__list_iterator<int, void *>' and 'std::__list_iterator<int, void *>') ``` and its chain ended with a note pointing at line 6 of the user's file, the `std::sort` call. GCC with libstdc++ uses different wording and different internal names, but the structure is the same: an error deep in the library, and a chain of notes that leads back to the call. The cause: `std::sort` requires **random-access iterators** (it subtracts and compares them), while `std::list` provides **bidirectional** ones. `std::list` has its own member function, `std::list::sort`, which relinks nodes instead. ## GCC options that shorten or clarify the output | Option | Effect (GCC 16 manual) | |---|---| | `-Wfatal-errors` | Stop at the first error | | `-fmax-errors=n` | Stop after `n` errors (0, the default, means no limit) | | `-ftemplate-backtrace-limit=n` | Maximum instantiation notes per diagnostic; default 10 | | `-fdiagnostics-show-template-tree` | Print mismatching template types as a tree, highlighting the differing parts | | `-fno-elide-type` | Print common parts of mismatching types instead of `[...]` | | `-fconcepts-diagnostics-depth=n` | How deep to explain an unsatisfied constraint; default 1 | | `-fno-diagnostics-show-nesting` | Restore the flat layout instead of GCC 16's indented, nested one | Two GCC 16 details are worth knowing: - By default its text output shows nested sub-diagnostics, "such as for problems when instantiating C++ templates", with indentation and bullet points, moving locations onto separate lines. The flat older look is one flag away. - When two long types fail to convert, GCC elides their common parts as `[...]`; the template tree shows exactly which argument differs, for example `vector<[double != float]>`. ## Concepts make the message short C++20 constrained algorithms state their requirements up front. Replacing the call with `std::ranges::sort(latencies)` made the same compiler print 22 lines instead of 114, and the notes said directly that `std::list<int>&` does not satisfy `random_access_range`. Raising `-fconcepts-diagnostics-depth` asks GCC to explain deeper into nested constraints when the first level is not enough. ## Habits that help - Build with **one error at a time** while hunting a template failure. - **Copy the type** from the first error into a small test instead of reading the whole log. - Prefer **constrained interfaces** in your own templates, so your users get the short message too. - Treat a long error as a **requirements mismatch**, not a compiler bug.
- Why does std::ranges::sort give a much shorter error for the same mistake?It is a C++20 constrained algorithm: its signature requires `random_access_range`, so its call operator's constraints reject the call before any algorithm body is instantiated. The compiler reports the unsatisfied constraint at your call site instead of failing deep inside the implementation.
- When would you raise -ftemplate-backtrace-limit instead of lowering errors?When the frame in your own code is not shown because the chain is longer than the default ten notes. Raising the limit, or setting it high, prints the full chain so you can find where your code entered the library.
- The last error in the log is the one to fix
- A long template error means the standard library has a bug
- std::sort accepts any iterator that supports ++
- -Wfatal-errors hides the real cause and should be avoided
- The fix belongs in the header where the error is reported
Assumes GCC 16.2: its manual documents nested, indented C++ diagnostics as the default text layout and a default template backtrace limit of 10.