quarkusio/quarkus · error · IllegalStateException

Unsupported RestClientProxy method: ${method}

Error message

Unsupported RestClientProxy method: ${method}

What it means

Thrown by invokeRestClientProxyMethod when code calls a method on the REST client proxy that is neither a @Path resource method nor one of the supported RestClientProxy methods (getClient, close, toString, hashCode, equals, etc.). The proxy only implements the interface contract, so unknown methods are rejected.

Source

Thrown at extensions/resteasy-classic/resteasy-client/runtime/src/main/java/io/quarkus/restclient/runtime/QuarkusProxyInvocationHandler.java:272

        }
        interfaces[0] = resourceInterface;
        final BeanManager beanManager = getBeanManager(resourceInterface);
        final Object proxy = Proxy.newProxyInstance(resourceInterface.getClassLoader(), interfaces,
                new QuarkusProxyInvocationHandler(resourceInterface, target, Set.copyOf(providers), client,
                        beanManager));
        ClientHeaderProviders.registerForClass(resourceInterface, proxy, beanManager);
        return proxy;
    }

    private Object invokeRestClientProxyMethod(final Method method) {
        switch (method.getName()) {
            case "getClient":
                return client;
            case "close":
                close();
                return null;
            default:
                throw new IllegalStateException("Unsupported RestClientProxy method: " + method);
        }
    }

    private void close() {
        if (closed.compareAndSet(false, true)) {
            if (creationalContext != null) {
                creationalContext.release();
            }
            client.close();
        }
    }

    private Type[] getGenericTypes(Class<?> aClass) {
        Type[] genericInterfaces = aClass.getGenericInterfaces();
        Type[] genericTypes = NO_TYPES;
        for (Type genericInterface : genericInterfaces) {
            if (genericInterface instanceof ParameterizedType) {
                genericTypes = ((ParameterizedType) genericInterface).getActualTypeArguments();

View on GitHub (pinned to e1c734241f)

Solutions

1. Call only methods declared on the client interface (or RestClientProxy/getClient/close)
2. Cast the proxy to the actual client interface type, not an implementation class
3. If you need the underlying client, use the getClient() method exposed by RestClientProxy
4. Check for wrapper/proxy frameworks that inject extra methods into the interface

Example fix

// before
Object proxy = RestClientBuilder.newBuilder().baseUri(uri).build(MyClient.class);
((MyClientImpl) proxy).someImplOnlyMethod(); // IllegalStateException: Unsupported RestClientProxy method
// after
MyClient proxy = RestClientBuilder.newBuilder().baseUri(uri).build(MyClient.class);
proxy.get(); // only interface methods

if (!(proxy instanceof MyClient)) {
    throw new IllegalArgumentException("proxy must implement the client interface");
}

static boolean supportsMethod(Object proxy, String methodName) {
    return proxy != null && Arrays.stream(proxy.getClass().getMethods())
        .anyMatch(m -> m.getName().equals(methodName));
}

try {
    return method.invoke(proxy, args);
} catch (InvocationTargetException e) {
    if (e.getCause() instanceof IllegalStateException
            && e.getCause().getMessage().startsWith("Unsupported RestClientProxy method")) {
        throw new UnsupportedOperationException("Call only methods on the client interface", e);
    }
    throw e;
}

When it happens

Trigger: Casting the proxy to a concrete class and calling non-interface methods; calling an added default/object method not handled by the switch; invoking methods via reflection that don't exist on the client interface or RestClientProxy.

Common situations: Wrapping proxies in libraries that add instrumentation methods; calling a method that exists on the impl class but not the interface; misuse of generic proxies in test code.

Related errors

• Proxy type HTTP is required
• RestClientProxy is closed
• proxyHost must not be null
• Invalid port number
• Neither baseUri nor baseUrl was specified

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/ab7a6f4ce97d17be. Report an issue: GitHub.