clojure/clojure · error · IllegalArgumentException

Can't find matching overloaded method

Error message

Can't find matching overloaded method: ${name.name}

What it means

The method name is overloaded and hints were supplied, but the hinted signature (method name + hinted parameter classes) does not match any of the available overloads, so matches.get(msig) returned null. The hints either name the wrong classes or the return-type hint doesn't line up with an actual overload.

Solutions

1. Check the exact declared parameter types in the interface javadoc and match them byte-for-byte (int vs Integer, CharSequence vs String).
2. Remove all hints so the compiler auto-matches if there is only one overload of that arity.
3. Use reflection on the interface class to list overloads: (.getMethods (clojure.lang.RT/classForName "Foo")).

Example fix

// before
(reify Iface
  (^String bar [this ^Integer x] (str x)))
// after
(reify Iface
  (bar [this ^int x] (str x)))

(defn declared-params [iface-class method-name arity]
  (map #(.getParameterTypes %)
       (filter #(and (= method-name (.getName %))
                     (= arity (.getParameterCount %)))
               (.getMethods iface-class))))
;; hint exactly one of these type lists before implementing

(try
  (eval reify-form)
  (catch IllegalArgumentException e
    (if (re-find #"Can't find matching overloaded method" (.getMessage e))
      (println "hinted signature matches no overload — check declared param types")
      (throw e))))

When it happens

Trigger: (reify Foo (^String bar [this ^Integer x] ...)) where no overload of bar takes Integer at that arity (e.g. only Long or Object exist), so the hinted signature key misses the map of overloads.

Common situations: Hinting with boxed types (Integer) where the interface declares primitive (int); hinting String where CharSequence is declared; copying hints from a different overload; hint drift after a library upgrade changed the interface.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Must hint overloaded method
• Can't find matching method
• Can't type hint a local with a primitive initializer
• Can't type hint a primitive local with a different type
• Cannot coerce to , use a cast instead

AI-assisted analysis of clojure/clojure@f3b143341d (2026-09-09). Data as JSON: /api/errors/8770ea23201a6886. Report an issue: GitHub.

Appendix: source

Thrown at src/jvm/clojure/lang/Compiler.java:9099

					p = Symbol.intern(p.name);
				Class pclass = tagClass(tag);
				pclasses[i] = pclass;
				psyms[i] = p;
				}
			Map matches = findMethodsWithNameAndArity(name.name, parms.count(), overrideables);
			Object mk = msig(name.name, pclasses);
			java.lang.reflect.Method m = null;
			if(matches.size() > 0)
				{
				//multiple methods
				if(matches.size() > 1)
					{
					//must be hinted and match one method
					if(!hinted)
						throw new IllegalArgumentException("Must hint overloaded method: " + name.name);
					m = (java.lang.reflect.Method) matches.get(mk);
					if(m == null)
						throw new IllegalArgumentException("Can't find matching overloaded method: " + name.name);
					if(m.getReturnType() != method.retClass)
						throw new IllegalArgumentException("Mismatched return type: " + name.name +
						", expected: " + m.getReturnType().getName()  + ", had: " + method.retClass.getName());
					}
				else  //one match
					{
					//if hinted, validate match,
					if(hinted)
						{
						m = (java.lang.reflect.Method) matches.get(mk);
						if(m == null)
							throw new IllegalArgumentException("Can't find matching method: " + name.name +
							                                   ", leave off hints for auto match.");
						if(m.getReturnType() != method.retClass)
							throw new IllegalArgumentException("Mismatched return type: " + name.name +
							", expected: " + m.getReturnType().getName()  + ", had: " + method.retClass.getName());
						}
					else //adopt found method sig

View on GitHub (pinned to f3b143341d)