alibaba/canal · error · IllegalArgumentException

canal.user = , but canal.passwd is empty , pls check https:

Error message

canal.user =  , but canal.passwd is empty , pls check https://github.com/alibaba/canal/issues/4941

What it means

Thrown during CanalController construction when the canal.user property is non-empty but canal.passwd is empty. This is a startup config-validation guard: a user with no password is almost always a misconfiguration (the password was forgotten or not escaped), not an intentional setup. It points to GitHub issue #4941 which documents the confusing auth failures this combination caused.

Source

Thrown at deployer/src/main/java/com/alibaba/otter/canal/deployer/CanalController.java:123

            System.setProperty(CanalConstants.CANAL_ALIYUN_SECRETKEY, secretkey);
        }

        // 准备canal server
        ip = getProperty(properties, CanalConstants.CANAL_IP);
        registerIp = getProperty(properties, CanalConstants.CANAL_REGISTER_IP);
        port = Integer.valueOf(getProperty(properties, CanalConstants.CANAL_PORT, "11111"));
        adminPort = Integer.valueOf(getProperty(properties, CanalConstants.CANAL_ADMIN_PORT, "11110"));
        embeddedCanalServer = CanalServerWithEmbedded.instance();
        embeddedCanalServer.setCanalInstanceGenerator(instanceGenerator);// 设置自定义的instanceGenerator
        int metricsPort = Integer.valueOf(getProperty(properties, CanalConstants.CANAL_METRICS_PULL_PORT, "11112"));
        embeddedCanalServer.setMetricsPort(metricsPort);

        this.adminUser = getProperty(properties, CanalConstants.CANAL_ADMIN_USER);
        this.adminPasswd = getProperty(properties, CanalConstants.CANAL_ADMIN_PASSWD);
        String user = getProperty(properties, CanalConstants.CANAL_USER);
        String passwd = getProperty(properties, CanalConstants.CANAL_PASSWD);
        if (StringUtils.isNotEmpty(user) && StringUtils.isEmpty(passwd)) {
            throw new IllegalArgumentException(
                "canal.user = " + user + " , but canal.passwd is empty , pls check https://github.com/alibaba/canal/issues/4941");
        }
        embeddedCanalServer.setUser(user);
        embeddedCanalServer.setPasswd(passwd);

        String canalWithoutNetty = getProperty(properties, CanalConstants.CANAL_WITHOUT_NETTY);
        if (canalWithoutNetty == null || "false".equals(canalWithoutNetty)) {
            canalServer = CanalServerWithNetty.instance();
            canalServer.setIp(ip);
            canalServer.setPort(port);
        }

        // 处理下ip为空，默认使用hostIp暴露到zk中
        if (StringUtils.isEmpty(ip) && StringUtils.isEmpty(registerIp)) {
            ip = registerIp = AddressUtils.getHostIp();
        }

        if (StringUtils.isEmpty(ip)) {

View on GitHub (pinned to 87be50e876)

Solutions

1. Set canal.passwd in canal.properties to the matching password (or the SCRAM/SHA1 hash if using hashed passwords).
2. If you intended no authentication, clear canal.user instead so both are empty.
3. Ensure no environment variable or -D override sets canal.user without also setting canal.passwd.
4. Restart Canal after correcting the properties.

Example fix

# before (canal.properties)
canal.user = canal
# canal.passwd =
# after
canal.user = canal
canal.passwd = yourPasswordOrHash

// Pre-flight config check before constructing CanalController
String user = properties.getProperty(CanalConstants.CANAL_USER);
String passwd = properties.getProperty(CanalConstants.CANAL_PASSWD);
if (StringUtils.isNotEmpty(user) && StringUtils.isEmpty(passwd)) {
    throw new IllegalArgumentException(
        "canal.user is set but canal.passwd is empty; set the password or clear the user.");
}

When it happens

Trigger: canal.properties (or the active properties source) sets canal.user but leaves canal.passwd blank. CanalController reads both via getProperty and checks isNotEmpty(user) && isEmpty(passwd).

Common situations: Migrating from anonymous to authenticated Canal clients and forgetting to set the password; a properties file where the password line was commented out; environment-variable override that set user but not passwd.

Related errors

• canal.admin.passwd is empty , pls check https://github.com/a
• unknow mode : for monitor
• can't find destination:
• unknown mode :
• invalid destinations expr

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