{"record":{"id":"82825efa9b19e7ce","repo":"apache/beam","slug":"solaceio-caught-stalesessionexception-restarting-the","errorCode":null,"errorMessage":"SolaceIO: Caught StaleSessionException, restarting the FlowReceiver.","messagePattern":"SolaceIO: Caught StaleSessionException, restarting the FlowReceiver\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/solace/src/main/java/org/apache/beam/sdk/io/solace/broker/SolaceMessageReceiver.java","lineNumber":57,"sourceCode":"    startFlowReceiver();\n  }\n\n  private void startFlowReceiver() {\n    retryCallableManager.retryCallable(\n        () -> {\n          flowReceiver.start();\n          return 0;\n        },\n        ImmutableSet.of(JCSMPException.class));\n  }\n\n  @Override\n  public BytesXMLMessage receive() throws IOException {\n    try {\n      return flowReceiver.receive(DEFAULT_ADVANCE_TIMEOUT_IN_MILLIS);\n    } catch (StaleSessionException e) {\n      startFlowReceiver();\n      throw new IOException(\n          \"SolaceIO: Caught StaleSessionException, restarting the FlowReceiver.\", e);\n    } catch (JCSMPException e) {\n      throw new IOException(e);\n    }\n  }\n\n  @Override\n  public void close() {\n    flowReceiver.close();\n  }\n}\n","sourceCodeStart":39,"sourceCodeEnd":69,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/solace/src/main/java/org/apache/beam/sdk/io/solace/broker/SolaceMessageReceiver.java#L39-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry the receive — the connector already called startFlowReceiver() to re-establish the flow.","Ensure the pipeline runner retries/continues on IOException from the source rather than failing the bundle permanently.","Check network stability and broker availability settings (reconnect retries in JCSMPProperties) to reduce stale sessions.","If stale sessions recur, tune `JCSMPProperties.RECONNECT_RETRIES`/`RECONNECT_RETRY_WAIT` and verify broker message-VPN health."],"exampleFix":"// caller pattern\nBytesXMLMessage msg;\ntry {\n  msg = receiver.receive();\n} catch (IOException e) {\n  if (e.getCause() instanceof StaleSessionException) {\n    msg = receiver.receive(); // flow restarted, retry\n  } else {\n    throw e;\n  }\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  msg = receiver.receive();\n} catch (IOException e) {\n  if (e.getCause() instanceof StaleSessionException) {\n    msg = receiver.receive(); // flow was restarted by the connector\n  } else { throw e; }\n}","preventionTips":["Tune JCSMP reconnect retries/wait in session properties","Monitor broker availability and HA failover events","Retry receives after any StaleSessionException — the connector auto-restarts the flow"],"tags":["solace","java","stale-session","reconnect","network"],"backgroundTag":"connection-refused","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}