OpenFeign/feign · error · EncodeException

${e.toString()}

Error message

${e.toString()}

What it means

When JAXB marshalling of the request object fails (JAXBException), JAXBEncoder wraps it in a Feign EncodeException whose message is e.toString(). Typical causes are objects or nested fields lacking JAXB annotations, or a class not registered with the JAXBContextFactory.

Solutions

1. Read e.getCause() for the precise JAXBException message and fix annotations accordingly.
2. Annotate the request class with @XmlRootElement/@XmlElement or register it via JAXBContextFactory.Builder.
3. Verify the object passed at runtime matches the interface's declared body type.

Example fix

// before
class Item { private String name; } // marshal throws JAXBException
// after
@XmlRootElement
class Item { @XmlElement public String name; }

// before encoding
if (!bodyClass.isAnnotationPresent(javax.xml.bind.annotation.XmlRootElement.class)
    && !bodyClass.isAnnotationPresent(jakarta.xml.bind.annotation.XmlRootElement.class)) {
  throw new IllegalArgumentException(bodyClass + " lacks @XmlRootElement");
}

try {
  encoder.encode(obj, type, template);
} catch (EncodeException e) {
  Throwable cause = e.getCause();
  log.error("JAXB marshal failed: {}", cause == null ? e.getMessage() : cause.getMessage());
}

When it happens

Trigger: encode() is called (via customEncoder) with an object whose class has no @XmlRootElement/@XmlElement annotations, contains un-marshalable nested types, or does not match the declared body type.

Common situations: Forgetting @XmlRootElement on the body class; sending DTOs generated without JAXB annotations; mismatch between the class registered in the JAXBContextFactory and the actual runtime body class.

Related errors

• ${e.toString()}
• JAXB only supports encoding raw types. Found
• JAXB only supports encoding raw types. Found
• JAXB only supports decoding raw types. Found
• ${e.toString()}

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

Appendix: source

Thrown at jaxb-jakarta/src/main/java/feign/jaxb/JAXBEncoder.java:67

  private final JAXBContextFactory jaxbContextFactory;

  public JAXBEncoder(JAXBContextFactory jaxbContextFactory) {
    this.jaxbContextFactory = jaxbContextFactory;
  }

  @Override
  public void encode(Object object, Type bodyType, RequestTemplate template) {
    if (!(bodyType instanceof Class)) {
      throw new UnsupportedOperationException(
          "JAXB only supports encoding raw types. Found " + bodyType);
    }
    try {
      Marshaller marshaller = jaxbContextFactory.createMarshaller((Class<?>) bodyType);
      StringWriter stringWriter = new StringWriter();
      marshaller.marshal(object, stringWriter);
      template.body(stringWriter.toString());
    } catch (JAXBException e) {
      throw new EncodeException(e.toString(), e);
    }
  }

  @Override
  public boolean canEncode(Object object, Type bodyType, RequestTemplate template) {
    return Util.isXmlContentType(template);
  }
}

View on GitHub (pinned to e2a1e27560)