alibaba/canal · error · ServiceException

集群模式不允许指定server启动

Error message

集群模式不允许指定server启动

What it means

Thrown by the instance start/stop operation when 'start' is requested on an instance whose nodeServer has a non-null clusterId. Cluster-mode instances are managed by the cluster (load balancing), so starting via a specific server is disallowed.

Source

Thrown at admin/admin-web/src/main/java/com/alibaba/otter/canal/admin/service/impl/CanalInstanceServiceImpl.java:285

        } else {
            if (nodeId == null) {
                return false;
            }
            nodeServer = NodeServer.find.byId(nodeId);
        }
        if (nodeServer == null) {
            return false;
        }
        CanalInstanceConfig canalInstanceConfig = CanalInstanceConfig.find.byId(id);
        if (canalInstanceConfig == null) {
            return false;
        }
        Boolean result = null;
        if ("start".equals(option)) {
            if (nodeServer.getClusterId() == null) { // 非集群模式
                return instanceOperation(id, "start");
            } else {
                throw new ServiceException("集群模式不允许指定server启动");
            }
        } else if ("stop".equals(option)) {
            if (nodeServer.getClusterId() != null) {
                // 集群模式,通知主动释放
                result = SimpleAdminConnectors.execute(nodeServer.getIp(),
                    nodeServer.getAdminPort(),
                    adminConnector -> adminConnector.releaseInstance(canalInstanceConfig.getName()));
            } else { // 非集群模式下直接将状态置为0
                return instanceOperation(id, "stop");
            }
        } else {
            return false;
        }

        if (result == null) {
            result = false;
        }
        return result;

View on GitHub (pinned to 87be50e876)

Solutions

1. For cluster-mode instances, start via the cluster mechanism (the cluster will schedule it), not per-server start.
2. Reassign the instance to a standalone server (serverId, clusterId null) if per-server start is required.
3. Stop is allowed in cluster mode (releases the instance), so use stop+cluster-reschedule instead of start.
4. Verify nodeServer.clusterId reflects the intended deployment mode.

NodeServer server = NodeServer.find.byId(serverId);
if ("start".equals(option) && server != null && server.getClusterId() != null) {
    throw new IllegalStateException("Cannot start a cluster-mode instance on a specific server");
}

When it happens

Trigger: POST a 'start' option for an instance attached to a cluster-mode server (nodeServer.getClusterId() != null). The start branch sees cluster mode and throws 'cluster mode does not allow starting on a specific server'.

Common situations: UI/operator manually starting an instance that belongs to a cluster; instance was migrated to cluster mode but operator still uses standalone start semantics; misconfiguration of server as standalone when it's in a cluster.

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/474730a73d4b80fa. Report an issue: GitHub.