C++

Fix 'No Matching Function for Call' in C++ — Reading GCC's Candidate List, Viable vs Not Viable, and Conversion Failures

This error is not 'the function does not exist.' The name was found, every declaration with that name became a candidate, and each candidate was then rejected for a reason GCC prints directly underneath it. Read the candidate notes in order and the fix is usually already written there: no known conversion, wrong argument count, or a template argument that could not be deduced consistently.

Written November 21, 2026 · Tested with GCC 13.3.0 · 15 min read

By the end of this guide
  • The first failure: no conversion from the argument to any parameter
  • The second failure: the argument count fits no candidate
  • The third failure: template argument deduction fails
  • Reading any candidate list: a short procedure

Written November 21, 2026

Tested with GCC 13.3.0

What this guide is

When a function call is compiled, the compiler first performs name lookup, which for function templates may be followed by template argument deduction, and collects every declaration the name refers to. Those declarations are the candidate functions. Overload resolution then trims the candidates to the viable functions: a candidate is viable only if its parameter count can accept the number of arguments given — exactly matching, trailing off into an ellipsis, or covered by default arguments for the parameters past the ones supplied — and only if, for every argument, there is an implicit conversion sequence that converts that argument to the corresponding parameter, with reference binding accounted for. If exactly one viable function is better than all the others, it is called. If no candidate survives the trimming, GCC reports no matching function for call and then lists the candidates it rejected, one note: block per candidate, each block naming the reason that candidate was not viable.

That structure is what makes this diagnostic unusually informative, and also what makes it easy to misread. The error: line names only the call and the argument types as GCC understood them. Everything actionable is in the notes below it: each candidate: line shows one declaration that was considered, and the indented note under it states why that declaration could not take this call. A candidate listed in the output is not a near miss the compiler almost accepted, and it is not viable — viable candidates produce no such list at all, because the call compiles. The list is a rejection log, and fixing the error means removing the rejection reason for at least one candidate, or adding a new candidate that has no rejection reason.

This guide works through the three rejection reasons that cover most real occurrences, in the order they usually arrive: no implicit conversion exists from the argument type to the parameter type, the argument count does not fit any candidate, and template argument deduction fails before viability is even tested. It finishes with one program in which all three calls are fixed, each at the coordinate its own note named.

Build every program in this guide with g++ -std=c++20 -g.

The first failure: no conversion from the argument to any parameter

The smallest useful failing program has two overloads and one argument that fits neither:

C++
#include <iostream>
#include <string>

void print(int value) {
    std::cout << "int = " << value << '\n';
}

void print(const char* text) {
    std::cout << "text = " << text << '\n';
}

int main() {
    std::string label = "veldica";
    print(label);
    return 0;
}
Terminal
$ g++ -std=c++20 -g -o mismatch mismatch.cpp
mismatch.cpp: In function ‘int main()’:
mismatch.cpp:14:10: error: no matching function for call to ‘print(std::string&)’
   14 |     print(label);
      |     ~~~~~^~~~~~~
mismatch.cpp:4:6: note: candidate: ‘void print(int)’
    4 | void print(int value) {
      |      ^~~~~
mismatch.cpp:4:16: note:   no known conversion for argument 1 from ‘std::string’ {aka ‘std::__cxx11::basic_string<char>’} to ‘int’
    4 | void print(int value) {
      |            ~~~~^~~~~
mismatch.cpp:8:6: note: candidate: ‘void print(const char*)’
    8 | void print(const char* text) {
      |      ^~~~~
mismatch.cpp:8:24: note:   no known conversion for argument 1 from ‘std::string’ {aka ‘std::__cxx11::basic_string<char>’} to ‘const char*’
    8 | void print(const char* text) {
      |            ~~~~~~~~~~~~^~~~

Read the output in its three layers. The error: line gives the call as GCC typed it: print(std::string&) — the argument is the variable label, an lvalue of type std::string, so the call is summarized with the reference form of that type. Then, for each overload, a candidate: note points at the declaration, and a second note under it gives the verdict on that candidate, with its caret span under the parameter that failed. For print(int), the verdict is no known conversion for argument 1 from 'std::string' ... to 'int'. For print(const char*), the same verdict with const char* as the target. Both candidates failed the same viability condition — for every argument there must be an implicit conversion sequence to the corresponding parameter — and each note names the exact argument position, source type, and target type of the missing conversion.

Two details in the wording repay attention. First, no known conversion is a statement about implicit conversion sequences, not about whether the value could be turned into the target type by some explicit operation. A std::string does hold characters that a const char* parameter could read, and the string's c_str() member returns exactly such a pointer — but c_str() is a member function call the programmer must write, not an implicit conversion the compiler may insert, so it does not make the candidate viable. An implicit conversion sequence consists of at most one user-defined conversion — one converting constructor or one conversion function — surrounded by standard conversion sequences; there is no step in that shape that calls an ordinary member function such as c_str() or data(). Second, the {aka 'std::__cxx11::basic_string<char>'} expansion is GCC reminding you that std::string is an alias for a specialization of basic_string; it is the same type, not a second, different type hiding behind the first, and it is not a hint that some other overload was meant.

Note also what did not happen: the compiler did not pick the "closest" candidate and complain inside it. With zero viable functions there is nothing to rank — ranking implicit conversion sequences only happens among viable functions, to choose the single best one. That is why the same overload set can produce a different diagnostic on a different call: give these two overloads a double argument and there is no error at all, because a double converts to int by a standard floating-integral conversion, making print(int) viable, while no conversion from double to const char* exists. Exact type identity between argument and parameter is not the viability test; existence of an implicit conversion sequence is.

The second failure: the argument count fits no candidate

The second rejection reason is checked before conversions are even considered, and its note is correspondingly blunt:

C++
#include <iostream>

void print(int value) {
    std::cout << "int = " << value << '\n';
}

void print(const char* text) {
    std::cout << "text = " << text << '\n';
}

int main() {
    print(42, 7);
    return 0;
}
Terminal
$ g++ -std=c++20 -g -o count count.cpp
count.cpp: In function ‘int main()’:
count.cpp:12:10: error: no matching function for call to ‘print(int, int)’
   12 |     print(42, 7);
      |     ~~~~~^~~~~~~
count.cpp:3:6: note: candidate: ‘void print(int)’
    3 | void print(int value) {
      |      ^~~~~
count.cpp:3:6: note:   candidate expects 1 argument, 2 provided
count.cpp:7:6: note: candidate: ‘void print(const char*)’
    7 | void print(const char* text) {
      |      ^~~~~
count.cpp:7:6: note:   candidate expects 1 argument, 2 provided

Here every argument is individually convertible — 42 is already an int — and the call still fails, because viability first requires the parameter list to be able to accept the number of arguments supplied. A candidate with more parameters than arguments is viable only when every parameter past the supplied ones has a default argument; a candidate with fewer parameters than arguments is viable only when it ends in an ellipsis. Neither overload here has either feature, so both notes say the same thing: candidate expects 1 argument, 2 provided. When every candidate note in an output carries this wording, the types are a distraction — the call and the declarations disagree about arity, and the fix is to change the call's argument count, add the parameter (with a default argument if existing one-argument calls must keep working), or add an overload with the parameter count the call actually uses.

Default arguments deserve one precise qualification, because they are the fix most often applied to the wrong failure. A default argument makes a candidate viable for calls that supply fewer arguments; it does nothing for a call whose arguments fail on conversion. Adding a defaulted second parameter to print(int) — turning it into print(int, int = 1) — leaves a call with a std::string argument exactly as broken as before: the candidate is still rejected with no known conversion for argument 1, because the first argument still has no conversion to int, and the new default only ever supplies the second argument. Read the note's wording before reaching for a default: expects N arguments is an arity problem a default can solve; no known conversion for argument K is a conversion problem it cannot.

The third failure: template argument deduction fails

A function template adds a step in front of viability. Before the template can be a candidate in the ordinary sense, its template arguments must be known — specified explicitly, or deduced from the function arguments. Deduction considers each parameter/argument pair separately and combines the results; if any pair fails to deduce, if different pairs yield different template arguments, or if an argument remains neither deduced nor specified, compilation fails. GCC reports that failure inside the same no matching function shape:

C++
#include <iostream>

template <typename T>
void log_value(T first, T second) {
    std::cout << first << ' ' << second << '\n';
}

int main() {
    log_value(1, 2.5);
    return 0;
}
Terminal
$ g++ -std=c++20 -g -o deduce deduce.cpp
deduce.cpp: In function ‘int main()’:
deduce.cpp:9:14: error: no matching function for call to ‘log_value(int, double)’
    9 |     log_value(1, 2.5);
      |     ~~~~~~~~~^~~~~~~~
deduce.cpp:4:6: note: candidate: ‘template<class T> void log_value(T, T)’
    4 | void log_value(T first, T second) {
      |      ^~~~~~~~~
deduce.cpp:4:6: note:   template argument deduction/substitution failed:
deduce.cpp:9:14: note:   deduced conflicting types for parameter ‘T’ (‘int’ and ‘double’)
    9 |     log_value(1, 2.5);
      |     ~~~~~~~~~^~~~~~~~

The note chain here is one level deeper than in the plain-overload failures, and the extra level is the diagnosis. The candidate is the template itself, template<class T> void log_value(T, T). Under it, template argument deduction / substitution failed: announces that the failure happened during deduction, before any instantiated function's viability was tested. Under that, the specific reason: deduced conflicting types for parameter 'T' ('int' and 'double'). The first parameter, T first, deduces T = int from 1; the second parameter, also spelled T, deduces T = double from 2.5. One template parameter cannot be two types, so deduction fails and the template never becomes a viable candidate — even though, had T been fixed, both arguments could have been converted to a common parameter type.

That last distinction is the one that unlocks the fixes. Deduction is not conversion: when deducing, the compiler is matching the argument's type against the pattern T to discover what T is, and two different discoveries conflict. Once T is known by other means, ordinary implicit conversions apply to the arguments as they would for any non-template function. So stating the template argument explicitly — log_value<double>(1, 2.5) — removes the need to deduce T at all; 1 then converts from int to the now-known double parameter by a standard conversion, and the call compiles, as the fixed program below shows. The other honest fixes change the declaration instead: give the two parameters independent template parameters when they are genuinely allowed to differ, or change the call so both arguments have the same type when they genuinely must agree.

Reading any candidate list: a short procedure

Whatever the overload set, the notes follow the same grammar, and this order of reading extracts the fix fastest:

  1. Read the error: line for the call's argument types as GCC understood them. If a type there surprises you — an alias expanded with {aka ...}, a reference form such as std::string&, a type different from the one you thought the expression had — the surprise itself may be the bug, and it is cheapest to resolve before reading further.
  2. For each candidate: note, read only its indented reason note first. Sort the reasons into the three families: candidate expects N argument(s), M provided (arity), no known conversion for argument K from 'X' to 'Y' (conversion), and template argument deduction / substitution failed: with its own sub-note (deduction). A long candidate list usually contains only one or two distinct reasons repeated.
  3. Fix the family, not the individual note. An arity family means the declarations and the call disagree about how many arguments there are. A conversion family means no candidate accepts this argument type implicitly — add the overload for the type you actually have, or write the explicit conversion (such as .c_str()) that makes an existing candidate's parameter reachable. A deduction family means a template parameter was asked to be two types at once, or could not be discovered from the arguments at all — state it explicitly, split it into two parameters, or make the arguments agree.
  4. If a candidate you expected is missing from the list entirely, the problem is earlier than overload resolution: candidates are the declarations found by name lookup (and, for templates, deduction) in the call's context. A declaration in another namespace that was never brought into scope, or one declared after the call without a prior declaration, is not rejected by overload resolution — it was never a candidate, and no candidate note will mention it.

The fixed program: one fix per rejection reason

The fixed program keeps the original two overloads, adds the overload the first failure was missing, reaches the pointer overload through the explicit conversion its note pointed at, and states the template argument the third failure could not deduce:

C++
#include <iostream>
#include <string>

void print(int value) {
    std::cout << "int = " << value << '\n';
}

void print(const char* text) {
    std::cout << "text = " << text << '\n';
}

void print(const std::string& text) {
    std::cout << "string = " << text << '\n';
}

template <typename T>
void log_value(T first, T second) {
    std::cout << first << ' ' << second << '\n';
}

int main() {
    std::string label = "veldica";
    print(label);
    print(label.c_str());
    print(42);
    log_value<double>(1, 2.5);
    return 0;
}
Terminal
$ g++ -std=c++20 -g -o fixed fixed.cpp
$ ./fixed
string = veldica
text = veldica
int = 42
1 2.5

Read the four output lines against the three failures. string = veldica is the first call, now served by the added print(const std::string&) overload: the argument binds directly to the reference parameter, no conversion sequence is needed, and the new candidate is viable where both originals were rejected. text = veldica is the same string reaching the original const char* overload, through label.c_str() written explicitly at the call site — the conversion the compiler was never going to insert on its own, now spelled by the programmer. int = 42 is the unremarkable exact-match call that was always viable, included to show the overload set still resolves ordinary calls the ordinary way. And 1 2.5 is the deduction failure discharged by stating <double>: with T given, 1 is converted to double for the first parameter — which is why it prints as 1, the double value formatted without a fractional part — and 2.5 matches the second parameter exactly. Nothing in the fixed program changes the two original overloads; every fix landed where its candidate note pointed, at the missing overload, at the call site's explicit conversion, and at the call site's explicit template argument.

The fixes, ranked

Add the overload for the argument type you actually have. Ranked first because a recurring no known conversion note against the same argument type is the signature of a missing overload, and one new declaration — here, print(const std::string&) — repairs every such call at once. Prefer a reference parameter for a class type the function only reads, so the fix does not trade the error for a copy at every call.

Write the explicit conversion at the call site when an existing overload is the right function. .c_str() for a const char* parameter is the standard instance: the target function exists and is correct, the argument holds exactly what it needs, and only the conversion between them is not implicit. Keep this fix at the call sites that need it rather than wrapping the argument type — the explicit call is the documentation that a representation change happened there.

Match the arity the declarations offer, or extend a declaration deliberately. For an expects N arguments family, either change the call, or add the parameter — with a default argument when existing shorter calls must keep compiling. A default argument is an arity tool only; applied to a conversion failure it changes nothing, as the unchanged no known conversion note for the defaulted overload shows.

State the template argument explicitly when deduction conflicts but a common type is intended. log_value<double>(1, 2.5) says in the source what the programmer meant: both arguments are to be treated as double. If the two parameters are in fact independent, the better fix is in the declaration — two template parameters instead of one shared T — because then deduction succeeds from the arguments as written and future callers are not required to repeat the explicit argument.

Which fix for which note

What the candidate note says Cause Fix
no known conversion for argument 1 from 'std::string' to 'int' No implicit conversion sequence exists from the argument type to this parameter type Add an overload taking the argument's type, or convert the argument explicitly at the call site
no known conversion for argument 1 from 'std::string' to 'const char*' The string's characters are reachable only through a member function, which is not an implicit conversion Call .c_str() (or .data()) at the call site, or add an overload for the string type
candidate expects 1 argument, 2 provided The call supplies more arguments than any candidate's parameter list can accept Drop the extra argument, add the parameter, or add an overload with the matching count
Same arity note on every candidate Arity is checked before conversions, so it masks any conversion problems behind it Fix the count first, then re-read the notes — conversion reasons may appear once arity passes
template argument deduction / substitution failed: / deduced conflicting types for parameter 'T' Two parameters sharing one template parameter deduced it to two different types State the template argument explicitly, give the parameters separate template parameters, or make the argument types agree
An expected overload is absent from the candidate list It was never found by name lookup in the call's context, so it never became a candidate Bring the declaration into scope (namespace, header, or an earlier declaration) before the call

Checklist

  • Treat the candidate list as a rejection log, not a shortlist: every candidate printed was found not viable, and the indented note under each one is the reason to remove.
  • Classify each reason before editing — arity (expects N arguments), conversion (no known conversion for argument K), or deduction (deduction/substitution failed) — because the three families have disjoint fixes and applying one family's fix to another family's failure changes nothing.
  • Check the argument types in the error: line against what you believe the expressions are; an {aka ...} expansion is the same type under its alias, not a different type.
  • Do not assume an argument must match a parameter's type exactly to be viable: a double argument makes an int parameter viable through a standard conversion, and exact-match thinking misdiagnoses calls that were never broken.
  • Do not reach for a default argument to fix a conversion failure: defaults supply missing trailing arguments and nothing else, and the no known conversion note survives them unchanged.
  • Remember that deduction precedes conversion for templates: a shared template parameter deduced to conflicting types fails even when every argument could convert to a common type, and stating the template argument explicitly is what lets those conversions happen.
  • If the overload you expected never appears as a candidate, stop reading notes and check name lookup instead — scope, namespace, and declaration order decide the candidate set before viability is tested.

Sources

  • cppreference, Overload resolution — for name lookup and template argument deduction preceding overload resolution, for the candidate-function set being the declarations found by that lookup, for the viability conditions on argument count, default arguments, ellipsis, and an implicit conversion sequence for every argument with reference binding accounted for, and for exactly one best viable function being required for the call to compile.
  • cppreference, Implicit conversions — for an implicit conversion sequence consisting of at most one user-defined conversion between standard conversion sequences, for the program being well-formed only when one unambiguous implicit conversion sequence exists, and for floating-integral conversion being a standard conversion.
  • cppreference, Template argument deduction — for deduction taking place after name lookup and before overload resolution, for each parameter/argument pair being deduced separately and then combined, and for compilation failing when different pairs yield different deduced template arguments or an argument remains neither deduced nor explicitly specified.

Keep Exploring