OpenFeign/feign · error · EncodeException

This form encoder has no delegate encoder, so it can only…

Error message

This form encoder has no delegate encoder, so it can only encode form and multipart requests, and ${bodyType} is neither. Register an encoder that handles it.

What it means

FormEncoder wraps an optional delegate Encoder. Without a delegate it can only encode Map-based form and multipart bodies itself; anything else (POJOs, plain objects) is rejected with this EncodeException at encode time.

Solutions

Construct the encoder with a delegate: new FormEncoder(new JacksonEncoder()) (or GsonEncoder, SpringEncoder, etc.)
Ensure the delegate actually supports the failing bodyType
If only form/multipart is ever sent, wrap the body in a Map or use the supported @Form/@SpringForm annotations

Example fix

// before
Encoder encoder = new FormEncoder();
// after
Encoder encoder = new FormEncoder(new JacksonEncoder());

Defensive patterns

Strategy: validation

Validate before calling

Encoder encoder = new FormEncoder(new JacksonEncoder());
// ensure bodyType is Map or supported by the delegate
if (!(body instanceof Map) && !(delegateSupports(bodyType))) {
  throw new IllegalArgumentException("unsupported body type for form encoder: " + bodyType);
}

Type guard

boolean isFormOrMultipart(Object body) {
  return body instanceof Map;
}

Try / catch

try {
  client.call(payload);
} catch (EncodeException e) {
  if (e.getMessage().contains("no delegate encoder")) {
    throw new ConfigurationException("register a delegate encoder (Jackson/Gson/Spring)");
  }
  throw e;
}

Prevention

Always instantiate FormEncoder with a delegate encoder
Centralize Feign client configuration so encoder setup is not duplicated or dropped
Unit-test that each endpoint's body type is supported by the configured encoder chain

When it happens

Trigger: Calling FormEncoder constructed with the no-arg constructor (NO_DELEGATE) and encoding a bodyType that is not a Map (form/multipart), e.g. a custom POJO or a String body.

Common situations: new FormEncoder() used for a client that also sends JSON/plain bodies; after upgrading feign-form the single-arg constructor call was dropped; encoders were reconfigured and the delegate was lost.

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/158df7f8444a85bd. Report an issue: GitHub.

Appendix: source

Thrown at form/src/main/java/feign/form/FormEncoder.java:56

import lombok.experimental.FieldDefaults;
import lombok.val;

/**
 * A Feign's form encoder.
 *
 * @author Artem Labazin
 */
@FieldDefaults(level = PRIVATE, makeFinal = true)
public class FormEncoder implements Encoder {

  private static final String CONTENT_TYPE_HEADER;

  private static final Pattern CHARSET_PATTERN;

  /** Stands in for a delegate that was never supplied, see {@link #FormEncoder(Encoder)}. */
  private static final Encoder NO_DELEGATE =
      (object, bodyType, template) -> {
        throw new EncodeException(
            "This form encoder has no delegate encoder, so it can only encode form and multipart"
                + " requests, and "
                + bodyType
                + " is neither. Register an encoder that handles it.");
      };

  static {
    CONTENT_TYPE_HEADER = "Content-Type";
    CHARSET_PATTERN = Pattern.compile("(?<=charset=)([\\w\\-]+)");
  }

  Encoder delegate;

  Map<ContentType, ContentProcessor> processors;

  /** Constructor with the default Feign's encoder as a delegate. */
  public FormEncoder() {
    this(new DefaultEncoder());

View on GitHub (pinned to e2a1e27560)