What causes "at least one decoder is required" in OpenFeign/feign?

Add at least one decoder before build(), e.g. .add(new JacksonDecoder())

OpenFeign/feign · error · IllegalStateException

at least one decoder is required

Error message

at least one decoder is required

What it means

The MultiDecoder.Builder requires at least one decoder before building; calling build() on an empty builder throws this IllegalStateException immediately. It is a fail-fast guard so a misconfigured client never reaches runtime with no way to decode responses.

Solutions

Add at least one decoder before build(), e.g. .add(new JacksonDecoder())
If decoders come from a dynamic list, guard the build: only build the MultiDecoder when the list is non-empty, otherwise use a default decoder
Check whether an optional codec dependency is missing so the conditional add was skipped

Example fix

// before
MultiDecoder d = new MultiDecoder.Builder().build();
// after
MultiDecoder d = new MultiDecoder.Builder().add(new Decoder.Default()).build();

Defensive patterns

Strategy: validation

Validate before calling

if (decoders.isEmpty()) {
  decoders.add(new Decoder.Default()); // or fail fast with a clear config error
}
MultiDecoder decoder = new MultiDecoder.Builder().add(decoders.toArray(new Decoder[0])).build();

Try / catch

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

Prevention

Never call build() on a builder assembled from a possibly-empty dynamic list; append a default first
Unit-test client factory methods with assertions that decoders are non-empty
Centralize Feign client construction so decoder registration is in one audited place

When it happens

Trigger: Calling new MultiDecoder.Builder().build() (or a wrapper that builds it) without ever calling add(...) / withDefaultDecoder(...).

Common situations: Programmatic Feign.builder() configuration assembled from empty conditional lists (e.g. codecs added only when certain flags/classes are present, so the list ends up empty); copy-pasted builder code where the add lines were deleted; framework glue code constructing the builder dynamically.

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

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

Appendix: source

Thrown at core/src/main/java/feign/codec/MultiDecoder.java:241

     *     .add(DecoderPredicate.any(), new DefaultDecoder())
     *     .build();
     * </pre>
     *
     * @param predicate narrows what the decoder handles
     * @param decoder the decoder to delegate to
     */
    public Builder narrow(DecoderPredicate predicate, Decoder decoder) {
      return add(PredicatedDecoder.narrowing(predicate, decoder));
    }

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

View on GitHub (pinned to e2a1e27560)