OpenFeign/feign · error · IllegalArgumentException

exception attempting to instantiate

Error message

exception attempting to instantiate %s

What it means

feign-sax's SAXDecoder wraps a ContentHandler class that must expose a public no-arg constructor, invoked reflectively via ctor.newInstance() when a new handler instance is created for decoding. Any exception during reflective instantiation (no no-arg constructor, private constructor, constructor throwing, or class initializer failure) is rethrown as IllegalArgumentException with the constructor and cause attached. It is a configuration/class-shape error, not a runtime data error.

Solutions

1. Give the ContentHandler class a public no-arg constructor and make the class public and static (not an inner class).
2. Inspect the cause (e.getCause()) in the IllegalArgumentException to see why the constructor threw and fix the constructor body.
3. If the handler needs dependencies, initialize them inside the handler after construction or use a builder path that supports supplied instances instead of relying on reflection.

Example fix

// before
class OrderHandler implements ContentHandlerWithResult<Order> {
  OrderHandler(Parser p) { ... } // no no-arg ctor
}
// after
public class OrderHandler implements ContentHandlerWithResult<Order> {
  public OrderHandler() { ... }
}

Class<?> handlerClass = OrderHandler.class;
if (handlerClass.isMemberClass() && !java.lang.reflect.Modifier.isStatic(handlerClass.getModifiers())) {
  throw new IllegalStateException("ContentHandler must be a static/top-level class");
}
try {
  handlerClass.getDeclaredConstructor();
} catch (NoSuchMethodException e) {
  throw new IllegalStateException("ContentHandler needs a public no-arg constructor");
}

try {
  Order o = client.getOrder();
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("exception attempting to instantiate")) {
    // fix handler class shape; log e.getCause()
  }
}

When it happens

Trigger: Passing a class to SAXDecoder.builder() (via ContentHandlerWithResult registration / registeringContentHandler) whose declared constructor is missing, non-public, throws in its constructor or static initializer, or is an inner (non-static) class whose newInstance() call fails with InstantiationException, IllegalAccessException, or InvocationTargetException.

Common situations: Registering a non-static inner class as the content handler; giving the handler only a parameterized constructor; a constructor that throws NPE because a field dependency was not initialized; handler class not public.

Related errors

• Cannot instantiate exception with constructor
• ensure has a no-args constructor
• Cannot generate exception - check constructor parameter…
• Too many constructors marked with @FeignExceptionConstructor
• Cannot find any suitable constructor in class

AI-assisted analysis of OpenFeign/feign@e2a1e27560 (2026-09-10). Data as JSON: /api/errors/a0a4648c7c14e52d. Report an issue: GitHub.

Appendix: source

Thrown at sax/src/main/java/feign/sax/SAXDecoder.java:175

      private final Constructor<ContentHandlerWithResult<T>> ctor;

      private NewInstanceContentHandlerWithResultFactory(Class<ContentHandlerWithResult<T>> clazz) {
        try {
          this.ctor = clazz.getDeclaredConstructor();
          // allow private or package protected ctors
          ctor.setAccessible(true);
        } catch (NoSuchMethodException e) {
          throw new IllegalArgumentException("ensure " + clazz + " has a no-args constructor", e);
        }
      }

      @Override
      public ContentHandlerWithResult<T> create() {
        try {
          return ctor.newInstance();
        } catch (Exception e) {
          throw new IllegalArgumentException("exception attempting to instantiate " + ctor, e);
        }
      }
    }
  }

  @Override
  public boolean canDecode(Response response, Type type) {
    return Util.isXmlContentType(response);
  }
}

View on GitHub (pinned to e2a1e27560)