Read a C++20 Concepts Error — "Constraints Not Satisfied", Clause by Clause
The last note in a concepts diagnostic is the answer; everything above it is the route. This guide reads three GCC failures from the call site down to the single clause that evaluated to false, shows how Clang phrases the same failures in fewer lines, and fixes each call by changing the argument to a type that satisfies the clause the compiler named.
Written November 21, 2026 · Tested with GCC 13.3.0 · 18 min read
- The first failure: one clause, evaluated to false
- The second failure: a conjunction where only one clause fails
- The third failure: a required expression that is invalid
- The rule underneath all three diagnostics
Written November 21, 2026
Tested with GCC 13.3.0 and Clang 18.1.3
What this guide is
A concept is a named set of requirements on a template argument, and a constraint is the sequence of logical operations that specifies those requirements. When a call fails a constraint, the compiler does not stop at no matching function: it prints the candidate it rejected, the words constraints not satisfied, and then a chain of notes that walks from the call, through each concept in the constraint, down to the one atomic constraint whose expression evaluated to false or whose required expression was invalid. Read from the bottom up, that chain is a complete diagnosis. Read only at the top, it looks like the template itself is broken.
This guide reads three failures in that order. The first is the smallest possible case: one concept, one atomic constraint, one wrong argument type. The second adds a conjunction: the argument satisfies the first clause and fails only the second, and the diagnostic proves which is which by naming only the failed clause. The third uses a custom concept with a requires expression, where the failing requirement is not a value that evaluated to false but an expression that is not valid at all for the type. Clang's diagnostics for the same three programs follow, because the two compilers arrange the same facts differently and a reader who can parse one layout can usually parse the other. The fixed program at the end calls the same three functions with types that satisfy the named clauses.
Build every program in this guide with -std=c++20 -g, with g++ for the GCC diagnostics and clang++ for the Clang diagnostics. Nothing here needs a newer standard: concepts, std::integral, std::signed_integral, and requires expressions are all C++20.
The first failure: one clause, evaluated to false
The smallest failing program constrains a function with std::integral and calls it with a double:
#include <concepts>
#include <iostream>
template<std::integral T>
T twice(T value) {
return value + value;
}
int main() {
std::cout << twice(2.5) << '\n';
return 0;
}
$ g++ -std=c++20 -g -o integral integral.cpp
integral.cpp: In function ‘int main()’:
integral.cpp:10:23: error: no matching function for call to ‘twice(double)’
10 | std::cout << twice(2.5) << '\n';
| ~~~~~^~~~~
integral.cpp:5:3: note: candidate: ‘template<class T> requires integral<T> T twice(T)’
5 | T twice(T value) {
| ^~~~~
integral.cpp:5:3: note: template argument deduction/substitution failed:
integral.cpp:5:3: note: constraints not satisfied
In file included from integral.cpp:1:
/usr/include/c++/13/concepts: In substitution of ‘template<class T> requires integral<T> T twice(T) [with T = double]’:
integral.cpp:10:23: required from here
/usr/include/c++/13/concepts:100:13: required for the satisfaction of ‘integral<T>’ [with T = double]
/usr/include/c++/13/concepts:100:24: note: the expression ‘is_integral_v<_Tp> [with _Tp = double]’ evaluated to ‘false’
100 | concept integral = is_integral_v<_Tp>;
| ^~~~~~~~~~~~~~~~~~
Read it as five steps. The error: line names the call and the deduced argument type: twice(double), at integral.cpp:10:23, the call in main. The first note: names the candidate that was considered and shows its constraint in the signature line, requires integral<T>. The next two notes are the verdict in general terms: deduction and substitution failed, and the reason is constraints not satisfied. Those three lines together say only that this candidate was rejected for a constraint reason, not a conversion reason and not an arity reason.
The chain below them is the specific reason. In substitution of ... [with T = double] fixes the type under test. required from here points back at the call site. required for the satisfaction of 'integral<T>' [with T = double] names the concept being checked. The last note is the atomic constraint itself, quoted from the library header at /usr/include/c++/13/concepts:100: concept integral = is_integral_v<_Tp>;, with the verdict the expression 'is_integral_v<_Tp> [with _Tp = double]' evaluated to 'false'. That is the whole diagnosis in one line: std::integral is defined as std::is_integral_v<T>, double is not an integral type, so the expression is false, so the concept is not satisfied, so the candidate is removed, so there is no matching function. Every line above the last note exists to connect that one false to the call that caused it. When a diagnostic is fifty lines long, the working move is the same: find the last evaluated to 'false' or is invalid note first, then read upward only far enough to confirm which call and which concept it belongs to.
The second failure: a conjunction where only one clause fails
std::signed_integral is a conjunction of two requirements. Its definition is integral<T> && is_signed_v<T>: the type must be integral, and it must be signed. A conjunction is satisfied only if both constraints are satisfied, and conjunctions are evaluated left to right. Call a function constrained by it with an unsigned int and exactly one of the two clauses can fail:
#include <concepts>
#include <iostream>
template<std::signed_integral T>
T negate(T value) {
return -value;
}
int main() {
std::cout << negate(42u) << '\n';
return 0;
}
$ g++ -std=c++20 -g -o signed signed.cpp
signed.cpp: In function ‘int main()’:
signed.cpp:10:24: error: no matching function for call to ‘negate(unsigned int)’
10 | std::cout << negate(42u) << '\n';
| ~~~~~~^~~~~
signed.cpp:5:3: note: candidate: ‘template<class T> requires signed_integral<T> T negate(T)’
5 | T negate(T value) {
| ^~~~~~
signed.cpp:5:3: note: template argument deduction/substitution failed:
signed.cpp:5:3: note: constraints not satisfied
In file included from signed.cpp:1:
/usr/include/c++/13/concepts: In substitution of ‘template<class T> requires signed_integral<T> T negate(T) [with T = unsigned int]’:
signed.cpp:10:24: required from here
/usr/include/c++/13/concepts:103:13: required for the satisfaction of ‘signed_integral<T>’ [with T = unsigned int]
/usr/include/c++/13/concepts:103:48: note: the expression ‘is_signed_v<_Tp> [with _Tp = unsigned int]’ evaluated to ‘false’
103 | concept signed_integral = integral<_Tp> && is_signed_v<_Tp>;
| ^~~~~~~~~~~~~~~~
The shape is identical to the first diagnostic until the last two lines, and those two lines carry the new information. The header line quoted is line 103, the full definition concept signed_integral = integral<_Tp> && is_signed_v<_Tp>;, and the caret span sits under the second operand only, is_signed_v<_Tp>. The note above it names only that expression: the expression 'is_signed_v<_Tp> [with _Tp = unsigned int]' evaluated to 'false'. There is no corresponding note for integral<_Tp>, because that clause was satisfied: an unsigned int is an integral type. The absence is data. In a conjunction diagnostic, GCC reports the clause that failed; a clause with no failure note under it passed. So this call does not need a different kind of type, it needs the signed half of the same kind: any signed integral type satisfies both clauses, and the fix is in the argument, not in the constraint.
The left-to-right evaluation order matters for reading longer conjunctions. Because a conjunction short-circuits, a type that fails the first clause may never have its later clauses checked at all, so a diagnostic that names the first clause does not prove the type would have passed the rest. The unsigned int case is the informative one precisely because it got past the first clause: the compiler checked both, and the note set shows one pass by silence and one failure by name. When you change the argument to fix a conjunction failure, re-read the new diagnostic rather than assuming the named clause was the only problem; a different argument can fail an earlier clause and produce a shorter chain that names that one instead.
The third failure: a required expression that is invalid
A custom concept built on a requires expression fails differently, because its requirements are expressions that must be valid, not just values that must be true. This concept requires that a + b exists and that its result is the same type as T:
#include <concepts>
#include <iostream>
template<class T>
concept Addable = requires(T a, T b) {
{ a + b } -> std::same_as<T>;
};
template<Addable T>
T combine(T a, T b) {
return a + b;
}
struct Token {
int id;
};
int main() {
Token x{1};
Token y{2};
std::cout << combine(x, y).id << '\n';
return 0;
}
Token has no operator+, so the required expression cannot be formed. A requires expression that contains an invalid expression evaluates to false rather than making the program ill-formed, which is what allows the failure to arrive as an ordinary constraint rejection with a readable note:
$ g++ -std=c++20 -g -o addable addable.cpp
addable.cpp: In function ‘int main()’:
addable.cpp:21:25: error: no matching function for call to ‘combine(Token&, Token&)’
21 | std::cout << combine(x, y).id << '\n';
| ~~~~~~~^~~~~~
addable.cpp:10:3: note: candidate: ‘template<class T> requires Addable<T> T combine(T, T)’
10 | T combine(T a, T b) {
| ^~~~~~~
addable.cpp:10:3: note: template argument deduction/substitution failed:
addable.cpp:10:3: note: constraints not satisfied
addable.cpp: In substitution of ‘template<class T> requires Addable<T> T combine(T, T) [with T = Token]’:
addable.cpp:21:25: required from here
addable.cpp:5:9: required for the satisfaction of ‘Addable<T>’ [with T = Token]
addable.cpp:5:19: in requirements with ‘T a’, ‘T b’ [with T = Token]
addable.cpp:6:9: note: the required expression ‘(a + b)’ is invalid
6 | { a + b } -> std::same_as<T>;
| ~~^~~
cc1plus: note: set ‘-fconcepts-diagnostics-depth=’ to at least 2 for more detail
Three differences from the trait-based failures mark this form. First, the chain stays in the program's own file: the concept is defined at addable.cpp:5, not in a library header, so the required for the satisfaction line and the failure line both point at user code. Second, there is an extra chain line the earlier diagnostics did not have, in requirements with 'T a', 'T b' [with T = Token], which names the local parameters of the requires expression: the compiler is reporting from inside the requirement list, with a and b standing in for values of type Token. Third, the verdict wording changes. There is no evaluated to 'false', because nothing was evaluated: the note says the required expression '(a + b)' is invalid, and the caret span covers exactly a + b inside the compound requirement on line 6. The -> std::same_as<T> half of that requirement is never reached, because the expression whose type it would have constrained does not exist for Token. The closing cc1plus note offers -fconcepts-diagnostics-depth= of at least 2 for more detail; at the default depth the invalid-expression note is already the actionable line, and the deeper replay adds the underlying overload failure for operator+ rather than a different cause.
The fix for this form is a choice the diagnostic frames but does not make. Either the type gains the required operation, an operator+ on Token returning a Token, or the call stops asking a non-addable type to satisfy a concept that requires addition. Which of those is right is a design question about whether adding two tokens means anything; the diagnostic's job, which it completes, is to name the missing operation and the exact requirement that asked for it.
The rule underneath all three diagnostics
A constraint is a sequence of logical operations over atomic constraints, formed by normalizing the constraint expression: an && forms a conjunction, an || forms a disjunction, and anything else is an atomic constraint, an expression together with the mapping from its template parameters to the arguments under test. An atomic constraint is satisfied when, after substitution, its expression is a constant expression of type bool that evaluates to true; if substitution produces an invalid type or expression, the atomic constraint is not satisfied. A conjunction is satisfied only if both sides are satisfied, evaluated left to right with short-circuiting; a disjunction is satisfied if either side is satisfied, also left to right. A concept is satisfied exactly when its constraint expression, normalized this way, is satisfied, and the standard library concepts in this guide are one or two atomic constraints each: std::integral<T> is the single atomic constraint std::is_integral_v<T>, and std::signed_integral<T> is the conjunction of std::integral<T> with std::is_signed_v<T>.
That model is the whole reading method. Every constraints not satisfied diagnostic is a report about that evaluation: the header lines name the candidate and the concept, the chain lines show the normalization path the compiler took, and the final note names the atomic constraint where evaluation stopped, either because its expression evaluated to false or because a required expression inside a requires expression was invalid and made the enclosing requirement false. There is no second, hidden failure list behind the printed one at the default diagnostic depth: the named clause is where this candidate died for this argument type, and fixing the call means supplying a type for which that clause, and every clause before it in the conjunction order, holds.
The same three failures in Clang
Clang prints the same failing clauses in fewer lines, in the opposite reading order: the specific reason comes immediately after the candidate note, phrased as because ..., before any header line is quoted. For the first program:
$ clang++ -std=c++20 -g -o integral_clang integral.cpp
integral.cpp:10:18: error: no matching function for call to 'twice'
10 | std::cout << twice(2.5) << '\n';
| ^~~~~
integral.cpp:5:3: note: candidate template ignored: constraints not satisfied [with T = double]
5 | T twice(T value) {
| ^
integral.cpp:4:10: note: because 'double' does not satisfy 'integral'
4 | template<std::integral T>
| ^
/usr/bin/../lib/gcc/x86_64-linux-gnu/13/../../../../include/c++/13/concepts:100:24: note: because 'is_integral_v<double>' evaluated to false
100 | concept integral = is_integral_v<_Tp>;
| ^
1 error generated.
The correspondences are one to one. GCC's candidate: plus constraints not satisfied becomes Clang's single line candidate template ignored: constraints not satisfied [with T = double]. GCC's chain of required for the satisfaction lines becomes Clang's because 'double' does not satisfy 'integral', pointed at the constraint in the program's own template head at line 4 rather than at the call. Both end at the same atomic constraint in the same header line, with nearly the same words: GCC's the expression 'is_integral_v<_Tp> [with _Tp = double]' evaluated to 'false' against Clang's because 'is_integral_v<double>' evaluated to false, with the template argument already substituted in Clang's rendering and the caret under the whole expression instead of a span. Clang also reports the error column at the function name, 10:18, where GCC reports the full call expression, 10:23; the line agrees, the column convention does not.
For the conjunction, Clang keeps the decisive property of the GCC output, naming only the failed clause:
$ clang++ -std=c++20 -g -o signed_clang signed.cpp
signed.cpp:10:18: error: no matching function for call to 'negate'
10 | std::cout << negate(42u) << '\n';
| ^~~~~~
signed.cpp:5:3: note: candidate template ignored: constraints not satisfied [with T = unsigned int]
5 | T negate(T value) {
| ^
signed.cpp:4:10: note: because 'unsigned int' does not satisfy 'signed_integral'
4 | template<std::signed_integral T>
| ^
/usr/bin/../lib/gcc/x86_64-linux-gnu/13/../../../../include/c++/13/concepts:103:48: note: because 'is_signed_v<unsigned int>' evaluated to false
103 | concept signed_integral = integral<_Tp> && is_signed_v<_Tp>;
| ^
1 error generated.
As in the GCC output, integral appears in the quoted definition line but earns no failure note of its own: the only evaluated to false note is for is_signed_v<unsigned int>, at the same header column, 103:48, in both compilers. A reader who learned the rule on one compiler, that an unmentioned clause in a conjunction passed, can trust it on the other.
For the requires-expression failure, Clang goes one step further than GCC at the default depth and states the underlying reason inline:
$ clang++ -std=c++20 -g -o addable_clang addable.cpp
addable.cpp:21:18: error: no matching function for call to 'combine'
21 | std::cout << combine(x, y).id << '\n';
| ^~~~~~~
addable.cpp:10:3: note: candidate template ignored: constraints not satisfied [with T = Token]
10 | T combine(T a, T b) {
| ^
addable.cpp:9:10: note: because 'Token' does not satisfy 'Addable'
9 | template<Addable T>
| ^
addable.cpp:6:9: note: because 'a + b' would be invalid: invalid operands to binary expression ('Token' and 'Token')
6 | { a + b } -> std::same_as<T>;
| ^
1 error generated.
Where GCC says the required expression '(a + b)' is invalid and offers a deeper diagnostics depth for the reason, Clang appends the reason to the same note: invalid operands to binary expression ('Token' and 'Token'). The practical differences across all three pairs are consistent: Clang is shorter, substitutes the concrete types into its note text, points its because note at the constraint as written in your code, and ends with an error count; GCC is longer, keeps the library's parameter names in its note text with the substitution shown separately in brackets, walks an explicit required from here chain through every concept layer, and offers -fconcepts-diagnostics-depth= when a requires expression hides a nested reason. For these three failures both outputs end at the same failing clause; they differ in how much of the chain you have to read to reach it, and, in the addable case, in whether the nested reason is printed inline, as Clang prints it, or offered behind a depth flag, as GCC offers it.
The fixed program: satisfy the named clauses
Each fix follows its diagnostic literally. twice asked for an integral type and got a double, so it is called with an int. negate asked for a signed integral type and got an unsigned int, so it is called with an int. combine asked for a type with a valid a + b returning that same type, so it is called with int, which has one. The three functions and the Addable concept are unchanged:
#include <concepts>
#include <iostream>
template<std::integral T>
T twice(T value) {
return value + value;
}
template<std::signed_integral T>
T negate(T value) {
return -value;
}
template<class T>
concept Addable = requires(T a, T b) {
{ a + b } -> std::same_as<T>;
};
template<Addable T>
T combine(T a, T b) {
return a + b;
}
int main() {
std::cout << "twice(21) = " << twice(21) << '\n';
std::cout << "negate(42) = " << negate(42) << '\n';
std::cout << "combine(20, 22) = " << combine(20, 22) << '\n';
return 0;
}
$ g++ -std=c++20 -g -o fixed fixed.cpp
$ ./fixed
twice(21) = 42
negate(42) = -42
combine(20, 22) = 42
The same program built with clang++ -std=c++20 -g prints the same three lines. Nothing about the constraints had to move: in all three failures the constraint stated the requirement correctly and the argument was the wrong type for it, which is the common case this error reports. The rarer case is the mirror image, where the diagnostic names a clause the function never meant to require, and then the fix is in the concept: a constraint copied from a stricter function, or a requires expression that asks for an operation the body never uses. The diagnostic cannot tell those two cases apart, because it reports satisfaction, not intent. It tells you exactly which clause failed for exactly which type; deciding whether the type or the clause is the mistake is the one step that stays with the reader, and it is a short step once the failing clause has been found.
The fixes, ranked
Change the argument to a type that satisfies the named clause. Ranked first because it is what the diagnostic directly supports: the last note names the failed expression and the type substituted into it, and passing a type for which that expression holds, an int for is_integral_v, a signed type for is_signed_v, removes the failure without weakening any requirement the function relies on.
Give the type the missing operation, when the operation is meaningful for it. For a requires-expression failure, the named invalid expression is the specification of what to add: an operator+ returning Token makes Token satisfy Addable. Do this only when the operation has a real meaning for the type; adding an operator purely to silence a constraint invents semantics the rest of the program will then trust.
Narrow or correct the concept, when the named clause was never intended. If the function body never uses the property the failed clause requires, the constraint is stricter than the function, and every correct call of the excluded kind will keep failing. Remove or weaken that clause, and let the diagnostic for the next genuinely wrong call name a clause the function actually needs.
Add an unconstrained or differently constrained overload, when both kinds of argument are legitimate. A function that should accept floating-point arguments as well as integral ones is two functions with two constraints, not one function with its constraint deleted. The overload keeps the constraint's documentation value for each path and keeps the diagnostics specific for the types neither path accepts.
Raise the diagnostics depth only when the default note does not name an actionable clause. GCC's -fconcepts-diagnostics-depth=2 or higher replays the failures nested inside a requires expression or a disjunction. It lengthens the output considerably, and for a single atomic constraint or a two-clause conjunction the default output already ends at the failed clause, so the flag is a tool for deep custom concepts, not a default setting.
Which fix for which cause
| What the diagnostic shows | Cause | Fix |
|---|---|---|
Last note: is_integral_v<...> evaluated to 'false' for a floating-point or class argument |
The argument type is not integral and the function requires std::integral |
Pass an integral argument, or add an overload for floating point if both are intended |
Last note names only the second clause of a conjunction, such as is_signed_v<...> |
The argument satisfies the earlier clauses and fails this one | Change only the property the named clause tests, here signedness; keep the rest of the type |
| Last note names the first clause of a conjunction and no later clause is mentioned | The argument failed early and later clauses were not checked, due to left-to-right short-circuiting | Fix the named clause, rebuild, and read the new diagnostic for any later clause that now surfaces |
Note: the required expression '(a + b)' is invalid inside a requires expression |
The type has no valid form of the required expression | Add the operation to the type if it is meaningful there, or do not call the constrained function with that type |
Clang note: because 'T' does not satisfy 'C', with the atomic note below it |
The same failure in Clang's layout: the atomic note is the cause, the does not satisfy line is the summary |
Read the lowest because note for the failed clause, then apply the fix for that clause |
| The named clause is one the function body never relies on | The constraint is stricter than the function it guards | Correct the concept or the requires clause; the argument type is not the mistake |
Checklist
- Find the last note first: an
evaluated to 'false'expression or anis invalidrequired expression. That note, not theerror:line, states the cause. - Confirm the type under test from the
[with T = ...]substitution line, and the call that triggered it from therequired from hereline or theerror:line, before changing anything. - In a conjunction, treat unmentioned clauses as satisfied for this argument, and the first mentioned clause as the stopping point: later clauses after a short-circuited failure may be unchecked, not passed.
- Distinguish the two verdict wordings:
evaluated to 'false'means the expression formed and its value was wrong;is invalidmeans the expression could not be formed for this type at all. The fixes differ, a different argument value never repairs either, and a different argument type repairs the first while a missing operation is the second's subject. - Check whether the failing concept is defined in a library header or in your own code: the header line quoted in the note tells you, and a failure inside your own concept definition is read at the line of the requirement, not at the call.
- After changing the argument, rebuild and re-read: a new diagnostic naming a different clause is progress through the conjunction order, not a new bug.
- Keep Clang's layout in mind when switching compilers: the cause is the lowest
becausenote, the error column points at the function name, and the total error count at the end is not a count of distinct causes.
Related guides on this site
- Migrating a Template Library from SFINAE to C++20 Concepts — how enable-if and trait-based constraints are rewritten as concepts in the first place; this guide starts where that one ends, at the first call that fails the rewritten constraint.
- Daily C++ Tip 2: Constrain a function with a concept, in the parameter list — the short introduction to what a concept is and how a constrained template is written; this guide is the diagnostic half of the same subject, for when the written constraint rejects a call.
- Fix a Dangling std::string_view — Lifetime Rules for Views and References to Temporaries — another long compiler-adjacent report read line by line, there a sanitizer report and a warning rather than a constraint chain; the reading discipline, last decisive line first, is the same.
Sources
- cppreference, Constraints and concepts — for concepts as named sets of requirements, for the three kinds of constraint with conjunctions evaluated left to right and short-circuited, for atomic constraints being satisfied exactly when their substituted expression is a constant expression of type bool that evaluates to true, and for constraint normalization.
- cppreference, Concepts library — for the standard library concepts as compile-time validation of template arguments, and for a concept being satisfied when its syntactic requirements are met.
- cppreference, std::integral — for the definition
concept integral = std::is_integral_v<T>and for the concept being satisfied if and only if the type is an integral type. - cppreference, std::signed_integral — for the definition
concept signed_integral = std::integral<T> && std::is_signed_v<T>and for the concept being satisfied if and only if the type is integral andstd::is_signed_v<T>is true. - cppreference, requires expression — for a requires expression yielding a bool describing the constraints, for an invalid expression inside its requirements making the requires expression evaluate to false rather than making the program ill-formed, and for simple, type, compound, and nested requirements.
- GCC, C++ Concepts (Using the GNU Compiler Collection) — for concepts in GCC as the specification of constraints on template arguments, used to extend overloading and partial specialization based on the properties of types.
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.