OpenFeign/feign · error · IllegalStateException

JAXBContextFactory must be non-null

Error message

JAXBContextFactory must be non-null

What it means

Same as error 101 in the javax jaxb module: JAXBDecoder.Builder.build() throws IllegalStateException when no JAXBContextFactory was provided, because the decoder cannot create unmarshallers without it.

Solutions

1. Supply a factory: new JAXBDecoder.Builder(new JAXBContextFactory.Builder().build()).build().
2. Share one JAXBContextFactory instance between JAXBEncoder and JAXBDecoder.
3. Add a startup smoke test that builds the Feign client to validate wiring.

Example fix

// before
new JAXBDecoder.Builder().build();
// after
new JAXBDecoder.Builder(new JAXBContextFactory.Builder().build()).build();

// before building
if (jaxbContextFactory == null) {
  throw new IllegalStateException("JAXBContextFactory is required to build JAXBDecoder");
}

When it happens

Trigger: new JAXBDecoder.Builder().build() without supplying a JAXBContextFactory instance.

Common situations: Omitting the factory when wiring Feign.builder().decoder(...); incomplete copied configuration; a factory variable that is null after refactoring.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• JAXBContextFactory must be non-null
• JAXBContextFactory must be non-null
• JAXBContextFactory must be non-null
• JAXBContextFactory must be non-null
• JAXBContextFactory must be non-null

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

Appendix: source

Thrown at jaxb/src/main/java/feign/jaxb/JAXBDecoder.java:122

  public static class Builder {
    private boolean namespaceAware = true;
    private JAXBContextFactory jaxbContextFactory;

    /** Controls whether the underlying XML parser is namespace aware. Default is true. */
    public Builder withNamespaceAware(boolean namespaceAware) {
      this.namespaceAware = namespaceAware;
      return this;
    }

    public Builder withJAXBContextFactory(JAXBContextFactory jaxbContextFactory) {
      this.jaxbContextFactory = jaxbContextFactory;
      return this;
    }

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

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

View on GitHub (pinned to e2a1e27560)