OpenFeign/feign · error · IllegalStateException

Default method handler invoked before proxy has been bound.

Error message

Default method handler invoked before proxy has been bound.

What it means

Thrown by DefaultMethodHandler.bindTo when attempting to bind a handler that already has a non-null handle, i.e., bindTo was called a second time on the same DefaultMethodHandler instance. Per the contract in the Javadoc, a handler must be bound exactly once per instance; this is an internal guard against double binding of a Java default method invocation handle, typically caused by reusing a handler across proxy creations.

Solutions

1. Do not reuse DefaultMethodHandler instances across multiple Feign.newInstance calls; create fresh handlers for each proxy
2. If binding manually, ensure bindTo is invoked exactly once per handler instance
3. Report as a Feign bug if it occurs with the public Feign.builder() API, since binding is normally managed internally

When it happens

Trigger: Thrown at core/src/main/java/feign/DefaultMethodHandler.java:143 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at core/src/main/java/feign/DefaultMethodHandler.java:143

   * was called on the proxy object. Must be called once and only once for a given instance of
   * DefaultMethodHandler
   */
  public void bindTo(Object proxy) {
    if (handle != null) {
      throw new IllegalStateException(
          "Attempted to rebind a default method handler that was already bound");
    }
    handle = unboundHandle.bindTo(proxy);
  }

  /**
   * Invoke this method. DefaultMethodHandler#bindTo must be called before the first time invoke is
   * called.
   */
  @Override
  public Object invoke(Object[] argv) throws Throwable {
    if (handle == null) {
      throw new IllegalStateException(
          "Default method handler invoked before proxy has been bound.");
    }
    return handle.invokeWithArguments(argv);
  }
}

View on GitHub (pinned to e2a1e27560)