Graceful shutdown is a built-in capability of ApsaraMQ for RocketMQ that prevents message loss and client errors during server-side operations. When the server undergoes version releases, restarts, or maintenance, ApsaraMQ for RocketMQ activates protection mechanisms to prevent abrupt client disconnections and ensure business continuity.
Protection mechanisms
Server-side write suspension
Before a storage node restarts, the server temporarily suspends write operations to that node. The restart proceeds only after no new messages are being written to the node. This ensures that all messages already submitted by clients are stored successfully.
Connection draining via GOAWAY
The ApsaraMQ for RocketMQ server uses the GOAWAY frame defined in the HTTP/2 protocol to gracefully close connections or notify clients that connections are about to close. This mechanism coordinates connection termination between the server and clients, prevents in-progress requests from being interrupted, and ensures system stability.
Effects
Producers — All message send requests are processed successfully. No send failures occur during the graceful shutdown process.
Consumers — Most messages are consumed successfully. In rare cases, a small number of messages backlogged on the restarting storage node may be redelivered because consumer offset commits fail during the transition.
SDK version requirements
To use graceful shutdown, your client SDK must meet the following minimum version requirements:
SDK for JavaSDK for JavaSDK for GoSDK for PythonSDK for C++SDK for C#
| Language | Minimum version | Reference |
| Java (gRPC protocol) | 5.0.7 | SDK for Java |
| Java (Remoting protocol) | 5.3.1 | SDK for Java |
| Go | 5.1.0-rc.1 | SDK for Go |
| Python | 5.0.4 | SDK for Python |
| C++ | 5.0.2 | SDK for C++ |
| C# | 5.1.0 | SDK for C# |
| Node.js | 1.0.1 | SDK for Node.js |
Usage notes
No client-side configuration required — Graceful shutdown is a server-side feature. You only need to upgrade your client SDK to a supported version.
Design consumers for idempotency — Consumer offset commits may fail during the brief transition period, which can cause a small number of messages to be redelivered. Ensure that your consumer logic can safely process the same message more than once.
Monitor SDK versions proactively — When you add new services or update dependencies, verify that your ApsaraMQ for RocketMQ client SDK still meets the minimum version requirements for graceful shutdown.