apache/beam · error · IOException

SolaceIO: Caught StaleSessionException, restarting the…

Error message

SolaceIO: Caught StaleSessionException, restarting the FlowReceiver.

What it means

SolaceMessageReceiver.receive catches a StaleSessionException from the underlying FlowReceiver, restarts the flow receiver, and throws this IOException to signal the caller that the current receive failed but recovery was initiated. It indicates the JCSMP session backing the flow went stale (e.g. reconnect timeout) — the SDK auto-recovers, but the in-flight receive is lost and must be retried.

Solutions

1. Retry the receive — the connector already called startFlowReceiver() to re-establish the flow.
2. Ensure the pipeline runner retries/continues on IOException from the source rather than failing the bundle permanently.
3. Check network stability and broker availability settings (reconnect retries in JCSMPProperties) to reduce stale sessions.
4. If stale sessions recur, tune `JCSMPProperties.RECONNECT_RETRIES`/`RECONNECT_RETRY_WAIT` and verify broker message-VPN health.

Example fix

// caller pattern
BytesXMLMessage msg;
try {
  msg = receiver.receive();
} catch (IOException e) {
  if (e.getCause() instanceof StaleSessionException) {
    msg = receiver.receive(); // flow restarted, retry
  } else {
    throw e;
  }
}

try {
  msg = receiver.receive();
} catch (IOException e) {
  if (e.getCause() instanceof StaleSessionException) {
    msg = receiver.receive(); // flow was restarted by the connector
  } else { throw e; }
}

When it happens

Trigger: Calling `receive()` when the broker/session connection was lost long enough for JCSMP to mark the session stale — network partition, broker failover, or long GC pause causing the flow's session to become unusable.

Common situations: Broker restarts or HA failover during streaming reads; unstable network between the pipeline worker and the Solace broker; the FlowReceiver idle past the broker's session keep-alive thresholds.

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

• Can not get unique key from solr
• Datadog write failed:
• Expansion request to transform service failed.
• Failed to retrieve secret bytes
• Request failed after exhausting retries. Max retries

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

Appendix: source

Thrown at sdks/java/io/solace/src/main/java/org/apache/beam/sdk/io/solace/broker/SolaceMessageReceiver.java:57

    startFlowReceiver();
  }

  private void startFlowReceiver() {
    retryCallableManager.retryCallable(
        () -> {
          flowReceiver.start();
          return 0;
        },
        ImmutableSet.of(JCSMPException.class));
  }

  @Override
  public BytesXMLMessage receive() throws IOException {
    try {
      return flowReceiver.receive(DEFAULT_ADVANCE_TIMEOUT_IN_MILLIS);
    } catch (StaleSessionException e) {
      startFlowReceiver();
      throw new IOException(
          "SolaceIO: Caught StaleSessionException, restarting the FlowReceiver.", e);
    } catch (JCSMPException e) {
      throw new IOException(e);
    }
  }

  @Override
  public void close() {
    flowReceiver.close();
  }
}

View on GitHub (pinned to 12126d8942)