apache/beam · error · IllegalArgumentException

Unknown AcknowledgeMode

Error message

Unknown AcknowledgeMode: %s

What it means

JmsIO's UnboundedJmsReader maps a JmsIO AcknowledgeMode enum value to the underlying JMS session acknowledge mode. If the mode value falls outside the handled cases, the reader throws this IllegalArgumentException. It signals an internal enum dispatch failure, normally from a custom or newly added AcknowledgeMode not yet mapped.

Solutions

1. Use one of the supported JmsIO.AcknowledgeMode values (AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, INDIVIDUAL_ACKNOWLEDGE).
2. Verify all Beam SDK jar versions on the runner classpath match (no mixed io/jms module versions).
3. If the mode is null, check why withAcknowledgeMode was skipped or passed a null value.

Example fix

// before
Read<JmsRecord> r = JmsIO.<JmsRecord>read().withAcknowledgeMode(null);
// after
Read<JmsRecord> r = JmsIO.<JmsRecord>read().withAcknowledgeMode(JmsIO AcknowledgeMode.AUTO_ACKNOWLEDGE);

JmsIO.AcknowledgeMode mode = spec.getAcknowledgeMode();
if (mode == null || !EnumSet.allOf(JmsIO.AcknowledgeMode.class).contains(mode)) {
  throw new IllegalStateException("unsupported acknowledge mode: " + mode);
}

boolean isSupportedMode(JmsIO.AcknowledgeMode m) {
  return m == JmsIO.AcknowledgeMode.AUTO_ACKNOWLEDGE
    || m == JmsIO.AcknowledgeMode.CLIENT_ACKNOWLEDGE
    || m == JmsIO.AcknowledgeMode.DUPS_OK_ACKNOWLEDGE
    || m == JmsIO.AcknowledgeMode.INDIVIDUAL_ACKNOWLEDGE;
}

try { pipeline.run(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown AcknowledgeMode")) { /* fix spec */ } throw e; }

When it happens

Trigger: Instantiating an UnboundedJmsReader whose source spec has an AcknowledgeMode not covered by the switch/if chain (e.g. a null mode or a mode added in a newer JmsIO version running against an older mapper).

Common situations: Programmatic construction of Read specs where withAcknowledgeMode is called with a hand-built or null value; version mismatch between pipeline construction and runner classpath.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Aliased enumerations not currently supported.
• An error occurred
• Attempting to add message
• buildDescriptor: couldn't retrieve coder
• Cannot convert unknown

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

Appendix: source

Thrown at sdks/java/io/jms/src/main/java/org/apache/beam/sdk/io/jms/JmsIO.java:759

        if (configuredCode != null) {
          return configuredCode;
        }
        String connectionClassName = this.connection.getClass().getName();
        if (connectionClassName.contains("org.apache.activemq.ActiveMQConnection")) {
          return 4;
        } else if (connectionClassName.contains("org.apache.qpid.jms")) {
          return 101;
        } else if (connectionClassName.contains("org.apache.activemq.artemis")) {
          return 101;
        } else {
          throw new IllegalArgumentException(
              String.format(
                  "Unknown JMS provider '%s' for INDIVIDUAL_ACKNOWLEDGE. "
                      + "Please specify the code explicitly via Read#withIndividualAcknowledgeModeCode(int).",
                  connectionClassName));
        }
      } else {
        throw new IllegalArgumentException(String.format("Unknown AcknowledgeMode: %s", mode));
      }
    }

    @Override
    public boolean start() throws IOException {
      Read<T> spec = source.spec;
      ConnectionFactory connectionFactory = spec.getConnectionFactory();
      try {
        Connection connection;
        if (spec.getUsername() != null) {
          connection = connectionFactory.createConnection(spec.getUsername(), spec.getPassword());
        } else {
          connection = connectionFactory.createConnection();
        }
        connection.start();
        this.connection = connection;
        if (spec.getAutoScaler() == null) {
          this.autoScaler = new DefaultAutoscaler();

View on GitHub (pinned to 12126d8942)