Fix 'Call of Overloaded Function Is Ambiguous' in C++ — Equally Good Conversions, and How Overload Ranking Breaks the Tie
This error is not 'no function fits.' At least two functions fit, every one of them is viable, and the ranking rules cannot name a single winner — each candidate is either exactly as good as the other on every argument, or better on one argument and worse on another. Read which arguments are tied and the fix follows: break the tie deliberately, in the direction you actually meant.
Written November 21, 2026 · Tested with GCC 13.3.0 · 9 min read
- The ranking in one paragraph
- The first failure: one argument, two conversions of the same rank
- The second failure: each overload wins one argument
- The third failure: two user-defined conversions, two destinations
Written November 21, 2026
Tested with GCC 13.3.0
What this guide is
Overload resolution runs in three steps. First the compiler builds the set of candidate functions from the declarations found by name lookup. Then it trims that set to the viable functions: a candidate is viable only if its parameter count can accept the number of arguments given and, for every argument, there is an implicit conversion sequence that converts that argument to the corresponding parameter. Finally it analyzes the viable set to determine the single best viable function, and that analysis is where this error is born.
The comparison is pairwise and strict. One viable function is better than another only if its implicit conversion for every argument is not worse than the other function's, and its conversion for at least one argument is better. If exactly one viable function is better than all the others, it is called. Otherwise compilation fails — and when the failure is that two or more viable functions remain, none of them ahead of the rest, GCC reports call of overloaded ... is ambiguous and lists the tied candidates, one note: line per candidate, with no further note underneath. That absence is itself the diagnosis: unlike a candidate that was rejected for a missing conversion or a wrong argument count, these candidates were not rejected at all. They passed viability and then tied.
Ties come in two shapes, and the three failures in this guide cover both. In the first shape the conversions are indistinguishable: two different conversion sequences have the same rank, and the ranking rules define no way to prefer one over the other. In the second shape each candidate wins somewhere: one is better for one argument and worse for another, so neither satisfies "not worse on every argument." Both shapes end at the same error line, and both are fixed the same way in principle — change something so that exactly one candidate is better than all the others, or so that only one candidate remains viable. What changes is only where the tie lives: in one argument's conversion rank, split across two arguments, or inside a user-defined conversion.
Build every program in this guide with g++ -std=c++20 -g.
The ranking in one paragraph
Every standard conversion sequence is assigned one of three ranks. Exact match covers no conversion at all and the trivial conversions such as lvalue-to-rvalue conversion. Promotion covers integral promotion and floating-point promotion. Conversion covers everything else in the standard set: integral conversion, floating-point conversion, floating-integral conversion, pointer conversion, pointer-to-member conversion, boolean conversion, and user-defined conversion of a derived class to its base. The rank of a whole standard conversion sequence is the worst of the ranks of the conversions it holds. A standard conversion sequence as a whole is always better than a user-defined conversion sequence, which in turn is always better than an ellipsis conversion sequence; two user-defined conversion sequences are ranked against each other only when they use the same conversion function or constructor, in which case the one whose following standard conversion sequence is better wins. Keep those three ranks in mind — every tie below is a place where two sequences land on the same rank, or where the better-on-one-argument rule cancels out.
The first failure: one argument, two conversions of the same rank
The smallest useful failing program has two overloads and one argument that converts to both parameter types equally well:
#include <iostream>
void print(long value) {
std::cout << "long = " << value << '\n';
}
void print(double value) {
std::cout << "double = " << value << '\n';
}
int main() {
print(42);
return 0;
}
$ g++ -std=c++20 -g -o equal equal.cpp
equal.cpp: In function ‘int main()’:
equal.cpp:12:10: error: call of overloaded ‘print(int)’ is ambiguous
12 | print(42);
| ~~~~~^~~~
equal.cpp:3:6: note: candidate: ‘void print(long int)’
3 | void print(long value) {
| ^~~~~
equal.cpp:7:6: note: candidate: ‘void print(double)’
7 | void print(double value) {
| ^~~~~
Both candidates are viable, because an int argument has an implicit conversion sequence to each parameter. For print(long), the conversion from int to long is an integral conversion. For print(double), the conversion from int to double is a floating-integral conversion. Both of those conversions sit in the same rank — Conversion — so the two standard conversion sequences have the same rank and neither is a proper subsequence of the other. They are indistinguishable conversion sequences: the ranking rules do not call either one better, so neither function is better than the other, and there is no best viable function to call.
Two common misreadings are worth clearing away. First, the compiler is not judging which conversion loses less information, or which target type is "closer" to int in size. Ranking is defined over the categories above, not over numeric closeness: an integral conversion and a floating-integral conversion of the same rank tie even though the values they produce are quite different in kind. Second, long being an integer type like int does not earn it a preference — there is no rule that prefers staying inside the integer family. If a preference like that is what you want, the program has to express it, which is what the fixes below do.
Note also the contrast with the neighboring error. Offer this same overload set an argument of a type that converts to neither parameter and the failure would be no matching function for call, with a no known conversion note under each candidate. Here the candidates carry no such note, because nothing about them failed. The call failed at the last step of overload resolution, not the second.
The second failure: each overload wins one argument
With more than one argument, a tie does not need any single conversion to be tied. It is enough for the wins to be split:
#include <iostream>
void print(int first, double second) {
std::cout << "int,double = " << first << ' ' << second << '\n';
}
void print(double first, int second) {
std::cout << "double,int = " << first << ' ' << second << '\n';
}
int main() {
print(1, 2);
return 0;
}
$ g++ -std=c++20 -g -o swapped swapped.cpp
swapped.cpp: In function ‘int main()’:
swapped.cpp:12:10: error: call of overloaded ‘print(int, int)’ is ambiguous
12 | print(1, 2);
| ~~~~~^~~~~~
swapped.cpp:3:6: note: candidate: ‘void print(int, double)’
3 | void print(int first, double second) {
| ^~~~~
swapped.cpp:7:6: note: candidate: ‘void print(double, int)’
7 | void print(double first, int second) {
| ^~~~~
Score the call argument by argument. For the first argument, 1, the int parameter of print(int, double) is an exact match, while the double parameter of print(double, int) needs a floating-integral conversion — so the first candidate is better on argument one. For the second argument, 2, the positions reverse: the int parameter of print(double, int) is an exact match, and the double parameter of print(int, double) needs the conversion — so the second candidate is better on argument two. Now apply the definition of a better function: a candidate must be not worse on every argument and better on at least one. The first candidate is worse on argument two, so it is not better than the second; the second candidate is worse on argument one, so it is not better than the first. No other candidates exist, so there is no best viable function, and the call is ambiguous even though no individual conversion in it was tied with anything.
This is the shape that surprises people most, because each overload looks like the obvious intent for one reading of the call: print(1, 2) could plausibly mean "an int and then something converted to double" or "something converted to double and then an int." The compiler does not resolve that plausibility contest — argument positions are compared independently, and a win in one position cannot compensate for a loss in another. There is no scoring total. The fix therefore has to remove the split itself: change an argument so one candidate wins or ties everywhere, add an overload that matches the call exactly in every position, or remove one of the mirrored overloads if it was never meant to coexist with the other.
The third failure: two user-defined conversions, two destinations
The third tie lives one level deeper, inside the argument itself. A class type can offer more than one way to become a built-in type, and if each way leads to a different viable overload, the tie is between the conversion functions:
#include <iostream>
struct Value {
operator long() const { return 42L; }
operator double() const { return 42.0; }
};
void show(long value) {
std::cout << "long = " << value << '\n';
}
void show(double value) {
std::cout << "double = " << value << '\n';
}
int main() {
Value v;
show(v);
return 0;
}
$ g++ -std=c++20 -g -o converted converted.cpp
converted.cpp: In function ‘int main()’:
converted.cpp:18:9: error: call of overloaded ‘show(Value&)’ is ambiguous
18 | show(v);
| ~~~~^~~
converted.cpp:8:6: note: candidate: ‘void show(long int)’
8 | void show(long value) {
| ^~~~
converted.cpp:12:6: note: candidate: ‘void show(double)’
12 | void show(double value) {
| ^~~~
An implicit conversion sequence has a fixed shape: at most one user-defined conversion — one converting constructor or one conversion function — surrounded by standard conversion sequences. Value offers two different user-defined conversions, so the argument has two different implicit conversion sequences on the table: one through operator long() reaching the long parameter of show(long), and one through operator double() reaching the double parameter of show(double). Each sequence makes its candidate viable, and each candidate's conversion is exact once its conversion function has run. But the rule for ranking two user-defined conversion sequences against each other applies only when both sequences use the same conversion function or constructor — then the better following standard conversion sequence decides. Here the two sequences use different conversion functions, so that rule never engages, the sequences are indistinguishable, and neither candidate is better. A program is well-formed only when there is one unambiguous implicit conversion sequence from the argument's type to the parameter's type; show(v) has two equally good ones pointing at different functions, which is exactly the ambiguity the error names.
The general lesson is that adding a conversion function to a class is adding a candidate route into every overload resolution that class ever participates in. One conversion function usually helps — it makes the class usable where the target type is expected. Two conversion functions to two types that both appear as overload parameters recreate this failure at every such call site, and the call sites cannot fix it by choosing more carefully among implicit conversions, because choosing among them is precisely what the ranking rules declined to do. Either the class offers one conversion, or the call site states the conversion it wants explicitly, as the fixed program does.
Reading any ambiguous output: a short procedure
Whatever the overload set, the output has the same grammar, and this order of reading extracts the fix fastest:
- Confirm the shape first: an
error:line saying the callis ambiguous, followed bycandidate:notes with no rejection reason under any of them. If a candidate does carry a reason note —no known conversion,candidate expects N arguments— that candidate was not viable, and the call belongs to theno matching functionfamily instead, or is a mix where the viable remainder still tied. - For each candidate, write down the conversion each argument needs to reach it, and the rank of that conversion: exact match, promotion, or conversion for standard sequences; the conversion function used, for user-defined sequences.
- Compare the candidates pairwise. If one candidate's row is the same rank as another's on every argument, the tie is indistinguishability — look for the argument where both conversions share a rank. If each candidate has a strictly better rank somewhere and a strictly worse rank somewhere else, the tie is a split win — look for the two arguments where the wins trade places.
- Decide which function the call was supposed to mean before editing anything. Every honest fix for this error is a way of writing that decision into the program — an argument cast, an exact-match overload, a changed literal — and a fix chosen without the decision just moves the ambiguity, or worse, silently resolves future calls the wrong way.
The fixed program: one tie-break per failure
The fixed program keeps every original overload and breaks each tie at the call site, stating in the source which candidate each call means:
#include <iostream>
void print(long value) {
std::cout << "long = " << value << '\n';
}
void print(double value) {
std::cout << "double = " << value << '\n';
}
void print(int first, double second) {
std::cout << "int,double = " << first << ' ' << second << '\n';
}
void print(double first, int second) {
std::cout << "double,int = " << first << ' ' << second << '\n';
}
struct Value {
operator long() const { return 42L; }
operator double() const { return 42.0; }
};
void show(long value) {
std::cout << "long = " << value << '\n';
}
void show(double value) {
std::cout << "double = " << value << '\n';
}
int main() {
print(42L);
print(1, 2.0);
Value v;
show(static_cast<long>(v));
return 0;
}
$ g++ -std=c++20 -g -o fixed fixed.cpp
$ ./fixed
long = 42
int,double = 1 2
long = 42
Read the three output lines against the three failures. long = 42 is the first call with its argument written as 42L, a long literal: now print(long) is an exact match and print(double) still needs a conversion, so one candidate is better on the only argument and the tie is gone. int,double = 1 2 is the split-win call with its second argument written as the double literal 2.0: print(int, double) is now an exact match on both arguments, while print(double, int) needs a conversion on both, so the first candidate is not worse anywhere and better somewhere — it wins outright, and it prints 2 for the double parameter because that is how the value 2.0 is formatted. long = 42 again is the user-defined tie discharged by static_cast<long>(v): the cast names operator long() explicitly, so the argument arriving at overload resolution is already a long, show(long) is an exact match, and operator double() never enters the resolution at all. Nothing in the fixed program removes an overload; every fix landed at the argument whose conversion was tied, which is where the missing information always was.
The fixes, ranked
Change the argument so the intended candidate wins outright. Ranked first because most ambiguous calls occur at one or a few call sites, and a suffix, a literal of the right type, or a static_cast at that site states the intent exactly where a reader will look for it. print(42L), print(1, 2.0), and show(static_cast<long>(v)) each leave the overload set untouched and make one candidate strictly better than the rest.
Add the exact-match overload when the tied call shape is the common one. If calls like print(42) — an int argument against long and double parameters — occur throughout a program, an added print(int) is an exact match for every one of them and beats both Conversion-rank candidates everywhere. Prefer this when the new overload has real work of its own to do; if its body would only forward to one of the existing overloads, the call-site fix above is the smaller statement of the same decision.
Remove one side of the tie when it was never meant to compete. A mirrored pair such as print(int, double) and print(double, int), or a second conversion function added to a class for one narrow use, will keep producing this error at new call sites as long as both sides exist. Deleting or renaming the overload that carries no distinct meaning — or making a conversion function explicit so it stops participating in implicit conversion sequences — removes the tie for every future call, not just the one that failed today. Keep this fix for ties that recur; for a single call site it changes more of the program than the error requires.
Which fix for which tie
| What the candidate list shows | Cause | Fix |
|---|---|---|
print(long) and print(double) tied for an int argument |
Integral conversion and floating-integral conversion have the same rank, Conversion | Write the argument as the intended type (42L), cast it, or add a print(int) overload |
print(int, double) and print(double, int) tied for (int, int) |
Each candidate is better on one argument and worse on the other, so neither is better overall | Change one argument to the intended type (print(1, 2.0)), add the exact (int, int) overload, or remove the mirrored overload |
show(long) and show(double) tied for a class argument with two conversion functions |
Two user-defined conversion sequences use different conversion functions, so no rule ranks them | Cast the argument to the intended type, remove one conversion function, or make one of them explicit |
| A candidate you expected is missing from the list | It was not viable, or was never found by name lookup, so it took no part in the tie | Read its absence separately — a non-viable candidate belongs to the no matching function diagnosis, not this one |
Checklist
- Treat the candidate list as a tie table, not a rejection log: every candidate printed was viable, and the missing piece is a reason for one of them to be better than all the others.
- Rank each argument's conversion before editing — exact match beats promotion, promotion beats conversion, and two conversions of the same rank on the deciding argument are indistinguishable.
- Remember that ranking is per argument and pairwise: a candidate must be not worse on every argument and better on at least one, and a win on one argument never compensates for a loss on another.
- Do not expect the compiler to prefer the conversion that loses less information or stays in the same type family — no such rule exists in the ranking.
- Count a class's conversion functions as overload-resolution routes: two of them leading to two different overload parameters make every such call ambiguous until one route is removed, made
explicit, or bypassed by a cast at the call site. - Fix the tie where the missing decision belongs: at the call site for a one-off call, in the overload set for a call shape that recurs, and in the class for a conversion function that should never have competed implicitly.
Related guides on this site
- Fix 'No Matching Function for Call' in C++ — Reading GCC's Candidate List, Viable vs Not Viable, and Conversion Failures — the neighboring diagnostic: there no candidate is viable at all, here every listed candidate is viable and the failure is that none of them wins.
- C++ Functions: Parameters, Overloads, and Default Arguments — the groundwork this error assumes: how overload sets are formed, what a parameter list accepts, and where default arguments change which candidates are viable.
- Fix 'Cannot Bind Non-const Lvalue Reference to an Rvalue' in C++ — Temporaries, Function Arguments, and const& — the reference-binding side of viability: a candidate whose reference parameter cannot bind to the argument is removed before ranking begins, so it can neither win nor tie.
Sources
- cppreference, Overload resolution — for overload resolution proceeding through candidate functions, viable functions, and determination of the single best viable function, for a function being better than another only when its conversions are not worse for every argument and better for at least one, for compilation failing when no exactly one best viable function exists, and for the ranking of implicit conversion sequences: the Exact match, Promotion, and Conversion ranks, a standard conversion sequence being better than a user-defined conversion sequence, and two user-defined conversion sequences being ranked by their second standard conversion sequence only when they use the same conversion function or constructor.
- cppreference, Implicit conversions — for an implicit conversion sequence consisting of a standard conversion sequence, at most one user-defined conversion, and a further standard conversion sequence, and for the program being well-formed only when one unambiguous implicit conversion sequence exists from the source type to the target type.
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.