OpenFeign/feign · error · IllegalStateException

at least one encoder is required

Error message

at least one encoder is required

What it means

The MultiEncoder.Builder requires at least one encoder; calling build() with none registered throws this IllegalStateException as a fail-fast guard. This prevents constructing an encoder that could never serialize any request body.

Solutions

1. Add at least one encoder before build(), e.g. .add(new Encoder.Default()) or .add(new JacksonEncoder())
2. Guard dynamic assembly: fall back to a default encoder when the candidate list is empty
3. Confirm the codec dependency providing the intended encoder is actually on the classpath

Example fix

// before
Encoder e = new MultiEncoder.Builder().build();
// after
Encoder e = new MultiEncoder.Builder().add(new Encoder.Default()).build();

if (encoders.isEmpty()) {
  encoders.add(new Encoder.Default());
}
MultiEncoder encoder = new MultiEncoder.Builder().add(encoders.toArray(new Encoder[0])).build();

try {
  this.encoder = multiEncoderBuilder.build();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("at least one encoder")) {
    throw new ConfigurationException("No encoders registered for Feign client", e);
  }
  throw e;
}

When it happens

Trigger: Calling new MultiEncoder.Builder().build() (or code that builds it) without any add(...) call.

Common situations: Dynamic configuration where encoders are added conditionally (e.g. only when a JSON library is detected) and all conditions failed; refactoring removed the add calls; template builder code copied without the registration lines.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• at least one decoder is required
• Status Code [ ] has already been declared to throw [ ] and…
• Unable to decode response ( ) ...
• Unable to encode ( ) ...
• This form encoder has no delegate encoder, so it can only…

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

Appendix: source

Thrown at core/src/main/java/feign/codec/MultiEncoder.java:237

     *     .add(EncoderPredicate.any(), new DefaultEncoder())
     *     .build();
     * </pre>
     *
     * @param predicate narrows what the encoder handles
     * @param encoder the encoder to delegate to
     */
    public Builder narrow(EncoderPredicate predicate, Encoder encoder) {
      return add(PredicatedEncoder.narrowing(predicate, encoder));
    }

    /**
     * Builds the multi-encoder.
     *
     * @throws IllegalStateException if no encoder was added
     */
    public MultiEncoder build() {
      if (encoders.isEmpty()) {
        throw new IllegalStateException("at least one encoder is required");
      }
      return new MultiEncoder(encoders);
    }
  }
}

View on GitHub (pinned to e2a1e27560)