OpenFeign/feign · error · IllegalStateException

JAXBContextFactory must be non-null

Error message

JAXBContextFactory must be non-null

What it means

SOAPEncoder.Builder requires a JAXBContextFactory to create Marshallers for serializing request bodies; build() throws IllegalStateException if the factory was never supplied. This fail-fast check prevents a broken encoder from being wired into a Feign client.

Solutions

1. Add .withJAXBContextFactory(jaxbFactory) to the SOAPEncoder.Builder before build().
2. Share a single JAXBContextFactory between the encoder and decoder builders.
3. Verify the factory construction (new JAXBContextFactory.Builder().build()) is executed before the encoder builder runs.

Example fix

// before
SOAPEncoder encoder = new SOAPEncoder.Builder().build();
// after
SOAPEncoder encoder = new SOAPEncoder.Builder()
    .withJAXBContextFactory(jaxbFactory)
    .build();

JAXBContextFactory factory = /* shared instance */;
java.util.Objects.requireNonNull(factory, "JAXBContextFactory must be created before building SOAPEncoder");

try {
  encoder = new SOAPEncoder.Builder().withJAXBContextFactory(factory).build();
} catch (IllegalStateException e) {
  if ("JAXBContextFactory must be non-null".equals(e.getMessage())) {
    throw new IllegalStateException("Encoder misconfigured: supply JAXBContextFactory", e);
  }
  throw e;
}

When it happens

Trigger: Calling new SOAPEncoder.Builder().build() without .withJAXBContextFactory(...) when configuring the soap-jakarta module's encoder.

Common situations: Builder chain copied from another encoder config; assuming SOAPEncoder has a default constructor; factory bean not yet initialized in the application context.

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

• JAXBContextFactory must be non-null
• JAXBContextFactory must be non-null
• JAXBContextFactory must be non-null
• at least one decoder is required
• at least one encoder is required

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

Appendix: source

Thrown at soap-jakarta/src/main/java/feign/soap/SOAPEncoder.java:220

    }

    /**
     * The protocol used to create message factory. Default is "SOAP 1.1 Protocol".
     *
     * @param soapProtocol a string constant representing the MessageFactory protocol.
     * @see SOAPConstants#SOAP_1_1_PROTOCOL
     * @see SOAPConstants#SOAP_1_2_PROTOCOL
     * @see SOAPConstants#DYNAMIC_SOAP_PROTOCOL
     * @see MessageFactory#newInstance(String)
     */
    public Builder withSOAPProtocol(String soapProtocol) {
      this.soapProtocol = soapProtocol;
      return this;
    }

    public SOAPEncoder build() {
      if (jaxbContextFactory == null) {
        throw new IllegalStateException("JAXBContextFactory must be non-null");
      }
      return new SOAPEncoder(this);
    }
  }

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

View on GitHub (pinned to e2a1e27560)