OpenFeign/feign · error · IllegalStateException

JAXBContextFactory must be non-null

Error message

JAXBContextFactory must be non-null

What it means

In the javax-based soap module, SOAPEncoder.Builder.build() fails fast with IllegalStateException if withJAXBContextFactory was not called, since the encoder cannot create Marshallers without the factory.

Solutions

1. Add .withJAXBContextFactory(factory) to the builder before build().
2. Create one shared JAXBContextFactory for both encoder and decoder.
3. Check that the factory is constructed before client wiring code runs.

Example fix

// before
new SOAPEncoder.Builder().build()
// after
new SOAPEncoder.Builder().withJAXBContextFactory(factory).build()

JAXBContextFactory factory = /* shared instance */;
java.util.Objects.requireNonNull(factory, "factory required before SOAPEncoder build");

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

When it happens

Trigger: Calling new SOAPEncoder.Builder().build() without supplying a JAXBContextFactory while configuring Feign's SOAP encoder.

Common situations: Omitted builder step; null injected factory; migrating between soap and soap-jakarta modules and losing the builder line.

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

Appendix: source

Thrown at soap/src/main/java/feign/soap/SOAPEncoder.java:224

    }

    /**
     * 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)