alibaba/canal · error · ServiceException

failed to subscribe with reason: {}

Error message

failed to subscribe with reason: {}

What it means

Thrown by doServerAdmin(String action) when a SERVER admin packet's ACK returns code > 0. The server rejected the requested server-level operation and supplied a reason message.

Source

Thrown at admin/admin-web/src/main/java/com/alibaba/otter/canal/admin/connector/SimpleAdminConnector.java:220

    @Override
    public String instanceLog(String destination, String fileName, int lines) {
        return doLogAdmin("instance", "file", destination, fileName, lines);
    }

    // ==================== helper method ====================

    private String doServerAdmin(String action) {
        try {
            writeWithHeader(Packet.newBuilder()
                .setType(PacketType.SERVER)
                .setBody(ServerAdmin.newBuilder().setAction(action).build().toByteString())
                .build()
                .toByteArray());

            Packet p = Packet.parseFrom(readNextPacket());
            Ack ack = Ack.parseFrom(p.getBody());
            if (ack.getCode() > 0) {
                throw new ServiceException("failed to subscribe with reason: " + ack.getMessage());
            }

            return ack.getMessage();
        } catch (IOException e) {
            throw new ServiceException(e);
        }
    }

    private String doInstanceAdmin(String destination, String action) {
        try {
            writeWithHeader(Packet.newBuilder()
                .setType(PacketType.INSTANCE)
                .setBody(InstanceAdmin.newBuilder()
                    .setDestination(destination)
                    .setAction(action)
                    .build()
                    .toByteString())
                .build()

View on GitHub (pinned to 87be50e876)

Solutions

1. Read ack.getMessage() appended to the exception for the server's stated reason.
2. Retry after the server reaches a stable state (verify server liveness first).
3. Ensure no concurrent admin action is mutating the server simultaneously.
4. Check server-side logs for the failure detail behind the error code.

try {
    connector.serverAdmin(action);
} catch (ServiceException e) {
    if (e.getMessage().contains("failed to subscribe")) {
        // transient server-state issue; wait for stable state then retry once
    }
    throw e;
}

When it happens

Trigger: Calling a server admin action (e.g. start/stop/reload server) over the connector; the server processes it and returns an ACK with positive error code, e.g. server not ready, already in that state, or lacking permission.

Common situations: Issuing a reload/start on a server that is down or mid-transition; the action is invalid for the server's current state; concurrent admin operations conflict; resource constraints on the server side.

Related errors

• canal.adminUser is empty , pls check https://github.com/alib
• canal.adminPasswd is empty , pls check https://github.com/al
• unsupported version at this client.
• expect handshake but found other type.
• unexpected packet type when ack is expected

AI-assisted analysis of alibaba/canal@87be50e876 (2026-08-14). Data as JSON: /api/errors/d23166b91b58da6e. Report an issue: GitHub.