OpenFeign/feign · error · IllegalStateException

JAXBContextFactory must be non-null

Error message

JAXBContextFactory must be non-null

What it means

JAXBDecoder.Builder.build() requires a JAXBContextFactory to have been set; if none was supplied it throws IllegalStateException. The decoder cannot create unmarshallers without the factory, so building without one is a configuration error detected immediately at construction time.

Solutions

1. Pass a factory: new JAXBDecoder.Builder(new JAXBContextFactory.Builder().build()).build().
2. Construct the JAXBContextFactory once and share it between JAXBEncoder and JAXBDecoder.
3. If JAXB decoding is not needed, remove the decoder wiring instead of building an unconfigured one.

Example fix

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

// before building
if (jaxbContextFactory == null) {
  throw new IllegalStateException("provide a JAXBContextFactory before JAXBDecoder.Builder.build()");
}

When it happens

Trigger: Calling new JAXBDecoder.Builder().build() without first passing a JAXBContextFactory to the builder.

Common situations: Copying Feign.builder() wiring snippets and forgetting the factory argument; a refactoring that drops the factory parameter leaving it null.

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

Appendix: source

Thrown at jaxb-jakarta/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)