apache/beam · error · RuntimeException

Error when creating unmarshaller from JAXB Context.

Error message

Error when creating unmarshaller from JAXB Context.

What it means

JAXBCoder lazily creates a thread-local JAXB Unmarshaller for XML deserialization. If JAXBContext.createUnmarshaller() fails, the ThreadLocal initialValue wraps the exception in this RuntimeException. Decoding XML elements will fail until the JAXB context/classes are fixed.

Solutions

1. Check the wrapped exception cause for the concrete JAXB failure and fix the annotated class.
2. Verify the JAXB runtime (jaxb-runtime) is bundled with the pipeline so workers can instantiate the Unmarshaller.
3. Confirm the record class is on the classpath in worker environments (use a fat jar / correct staging).
4. Validate the class with JAXBContext.newInstance(cls).createUnmarshaller() locally before submitting the pipeline.

Example fix

// before: missing runtime on Java 11
// after: add dependency
// implementation 'javax.xml.bind:jaxb-api:2.3.1'
// implementation 'org.glassfish.jaxb:jaxb-runtime:2.3.1'

try { JAXBContext.newInstance(recordClass).createUnmarshaller(); } catch (Exception e) { throw new IllegalStateException("Record class not JAXB-unmarshalable", e); }

try { coder = Jaxbcoder.of(Record.class); } catch (RuntimeException e) { throw new IllegalStateException("JAXB unmarshaller setup failed: " + e.getCause(), e); }

When it happens

Trigger: Creating a JAXBCoder for a class whose JAXBContext cannot produce an Unmarshaller, then attempting to decode bytes from the stream, invoking initialValue.

Common situations: Same root causes as marshaller failures: missing JAXB runtime on Java 11+, invalid JAXB annotations, classloading issues in pipeline workers where the annotated class is not visible to the JAXB provider.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Error binding classes to a JAXB Context.
• Error when creating marshaller from JAXB Context.
• at key is not supported
• A function must be provided to convert the input type into…
• A PValue contained in

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/a0bed186d8bb9d64. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/xml/src/main/java/org/apache/beam/sdk/io/xml/JAXBCoder.java:85

          @Override
          protected Marshaller initialValue() {
            try {
              JAXBContext jaxbContext = getContext();
              return jaxbContext.createMarshaller();
            } catch (JAXBException e) {
              throw new RuntimeException("Error when creating marshaller from JAXB Context.", e);
            }
          }
        };
    this.jaxbUnmarshaller =
        new EmptyOnDeserializationThreadLocal<Unmarshaller>() {
          @Override
          protected Unmarshaller initialValue() {
            try {
              JAXBContext jaxbContext = getContext();
              return jaxbContext.createUnmarshaller();
            } catch (Exception e) {
              throw new RuntimeException("Error when creating unmarshaller from JAXB Context.", e);
            }
          }
        };
  }

  /**
   * Create a coder for a given type of JAXB annotated objects.
   *
   * @param jaxbClass the {@code Class} of the JAXB annotated objects.
   */
  public static <T> JAXBCoder<T> of(Class<T> jaxbClass) {
    return new JAXBCoder<>(jaxbClass);
  }

  @Override
  public void encode(T value, OutputStream outStream) throws IOException {
    encode(value, outStream, Context.NESTED);
  }

View on GitHub (pinned to 12126d8942)