alibaba/canal · error · RuntimeException

Pulsar Consumer subscriptName required

Error message

Pulsar Consumer subscriptName required

What it means

Error "Pulsar Consumer subscriptName required" thrown in alibaba/canal.

Source

Thrown at client/src/main/java/com/alibaba/otter/canal/client/pulsarmq/PulsarMQCanalConnector.java:150

     * @param subscriptName 订阅和客户端名称，同一个订阅名视为同一个消费实例
     * @date 2021/9/18 08:54
     * @author chad
     * @since 1 by chad at 2021/9/18 完善
     */
    public PulsarMQCanalConnector(boolean isFlatMessage, String serviceUrl, String roleToken, String topic,
                                  String subscriptName){
        this(isFlatMessage, serviceUrl, roleToken, topic, subscriptName, null);
    }

    public PulsarMQCanalConnector(boolean isFlatMessage, String serviceUrl, String roleToken, String topic,
                                  String subscriptName, String listenerName){
        this.isFlatMessage = isFlatMessage;
        this.serviceUrl = serviceUrl;
        this.roleToken = roleToken;
        this.topic = topic;
        this.subscriptName = subscriptName;
        if (StringUtils.isEmpty(this.subscriptName)) {
            throw new RuntimeException("Pulsar Consumer subscriptName required");
        }
        this.listenerName = listenerName;
    }

    /**
     * 完全自定义的消费实例参数
     *
     * @date 2021/9/18 10:20
     * @author chad
     * @since 1 by chad at 2021/9/18 完善
     */
    public PulsarMQCanalConnector(boolean isFlatMessage, String serviceUrl, String roleToken, String topic,
                                  String subscriptName, int batchSize, int getBatchTimeoutSeconds,
                                  int batchProcessTimeoutSeconds, int redeliveryDelaySeconds, int ackTimeoutSeconds,
                                  boolean isRetry, boolean isRetryDLQUpperCase, int maxRedeliveryCount){
        this(isFlatMessage,
            serviceUrl,
            roleToken,

View on GitHub (pinned to 87be50e876)

Solutions

1. Set the Pulsar subscription name (subscriptName) in the connector configuration before connecting.
2. Ensure the same subscription name is used consistently so messages are not duplicated across consumers.

When it happens

Trigger: Thrown at client/src/main/java/com/alibaba/otter/canal/client/pulsarmq/PulsarMQCanalConnector.java:150 when the library encounters an invalid state.

Common situations: Missing Pulsar subscription name. Require the property at configuration load time rather than at first consume, and fail fast with the property key in the message.

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