apache/beam · error · IOException

Error creating JMS session

Error message

Error creating JMS session

What it means

UnboundedJmsReader.recreateSession() wraps any exception from connection.createSession(false, ackMode) in an IOException with the message 'Error creating JMS session'. The reader recreates the JMS session (e.g. after checkpoint finalize in CLIENT_ACKNOWLEDGE mode) and any failure talking to or authenticating with the broker surfaces as this IOException.

Source

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

    // Acknowlging messages need open consumer. Tracking active checkpoints allows delayed close of
    // session and consumer.
    private final AtomicInteger activeCheckpoints = new AtomicInteger(0);

    public UnboundedJmsReader(UnboundedJmsSource<T> source, PipelineOptions options) {
      this.source = source;
      this.checkpointMarkPreparer = JmsCheckpointMark.newPreparer(source.spec.getAcknowledgeMode());
      this.currentMessage = null;
      this.currentID = EMPTY;
      this.options = options;
    }

    /** recreate session and consumer. */
    private synchronized void recreateSession() throws IOException {
      try {
        int ackMode = getAckModeCode(source.spec.getAcknowledgeMode());
        this.session = this.connection.createSession(false, ackMode);
      } catch (Exception e) {
        throw new IOException("Error creating JMS session", e);
      }

      Read<T> spec = source.spec;
      Duration receiveTimeout =
          MoreObjects.firstNonNull(source.spec.getReceiveTimeout(), Duration.ZERO);
      receiveTimeoutMillis = receiveTimeout.getMillis();

      try {
        if (source.spec.getTopic() != null) {
          consumer = session.createConsumer(session.createTopic(spec.getTopic()));
        } else {
          consumer = session.createConsumer(session.createQueue(spec.getQueue()));
        }
      } catch (Exception e) {
        throw new IOException("Error creating JMS consumer", e);
      }
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify the broker is reachable and the JMS connection is still open when the reader recreates the session (check logs just before this error)
2. Inspect the wrapped cause exception for the root reason (auth failure, connection closed, quota) and fix that (credentials, network, broker limits)
3. Make the pipeline resilient to transient broker outages by restarting the worker or using Beam's retryable failure handling
4. Confirm ackMode is a supported AcknowledgeMode and the broker client supports the mapped session acknowledgment constant

Example fix

// no code change in Beam; ensure broker health before/at runtime
// before: connection broken -> createSession throws
// after: validate/reconnect the Connection before recreation
if (connection == null || isClosed(connection)) {
  connection = connectionFactory.createConnection(user, password);
  connection.start();
}
session = connection.createSession(false, ackMode);

// preflight: ensure broker connectivity before pipeline start
try (Connection c = connectionFactory.createConnection(user, pass)) { c.start(); }

try {
  reader.recreateSession();
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().equals("Error creating JMS session")) {
    // inspect e.getCause(); reconnect/restart with backoff for transient broker outages
  } else throw e;
}

When it happens

Trigger: reader.recreateSession() invoked while the JMS Connection is closed/broken, credentials are invalid, the broker rejects session creation (e.g. limits, shutdown), or the acknowledge mode mapping produces an unsupported session mode.

Common situations: Broker restarted or network drop between connection creation and session recreation; session quota exhausted on the broker; connection closed after an earlier failure and the reader attempts recreation; IBM MQ/Qpid rejecting session options.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Error creating JMS consumer
• RuntimeException
• Unable to encode constant members of ParamWindowedValueCoder
• Unable to decode constant members from payload for ParamWind
• ConnectionFactory ${className} does not exist. If using expa

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