OpenFeign/feign · error · IllegalStateException

JAXBContextFactory must be non-null

Error message

JAXBContextFactory must be non-null

What it means

SOAPDecoder.Builder requires a JAXBContextFactory to create JAXB contexts for unmarshalling SOAP bodies; build() refuses to construct a decoder without one by throwing IllegalStateException. This is a fail-fast builder check so misconfiguration surfaces at wiring time, not on first response.

Solutions

1. Call .withJAXBContextFactory(new JAXBContextFactory.Builder().build()) on SOAPDecoder.Builder before build().
2. Reuse one shared JAXBContextFactory instance for both SOAPEncoder and SOAPDecoder builders.
3. Ensure your DI framework actually injects a non-null factory into the configuration code.

Example fix

// before
SOAPDecoder decoder = new SOAPDecoder.Builder().build();
// after
SOAPDecoder decoder = new SOAPDecoder.Builder()
    .withJAXBContextFactory(jaxbFactory)
    .build();

JAXBContextFactory factory = /* built once */;
java.util.Objects.requireNonNull(factory, "JAXBContextFactory must be created before building SOAPDecoder");

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

When it happens

Trigger: Calling new SOAPDecoder.Builder().build() (or omitting .withJAXBContextFactory(...)) while configuring the Feign encoder/decoder for the soap-jakarta module.

Common situations: Copy-pasting a decoder setup from the plain JAXB module and forgetting the factory; assuming a default factory exists; DI wiring that leaves the factory null.

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

Appendix: source

Thrown at soap-jakarta/src/main/java/feign/soap/SOAPDecoder.java:174

    public Builder withSOAPProtocol(String soapProtocol) {
      this.soapProtocol = soapProtocol;
      return this;
    }

    /**
     * Alters the behavior of the code to use the {@link SOAPBody#getFirstChild()} in place of
     * {@link SOAPBody#extractContentAsDocument()}.
     *
     * @return the builder instance.
     */
    public Builder useFirstChild() {
      this.useFirstChild = true;
      return this;
    }

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

  @Override
  public boolean canDecode(Response response, Type type) {
    return Util.isXmlContentType(response);
  }
}

View on GitHub (pinned to e2a1e27560)