`use_tls` and `pulsar+ssl://` client behavior can differ

[mattsre]

While running Pulsar cluster proxies behind an AWS Load Balancer I ran into issues with TLS connections to the proxies using example code from this repository. Running the examples/consumer.py code with the client url set to an LB hostname and use_tls=True results in connection failures, whereas simply specifying pulsar+ssl:// the consumer works as expected. After checking docs it seems the use_tls argument is deprecated, but I would still expect the behavior between use_tls and pulsar+ssl:// to be the same. I can provide details on the load balancer configuration if needed.

Examples with some logs (fake hostname):

client = pulsar.Client("pulsar://pulsar-primary.acme.org:6651", use_tls=True)

This client produces connection errors like below:

2025-10-10 12:56:28.815 INFO  [0x1f7cd60c0] Client:86 | Subscribing on Topic < redacted_topic >
2025-10-10 12:56:28.815 INFO  [0x1f7cd60c0] ClientConnection:193 | [<none> -> pulsar://pulsar-primary.acme.org:6651] Create ClientConnection, timeout=10000
2025-10-10 12:56:28.815 INFO  [0x1f7cd60c0] ConnectionPool:124 | Created connection for pulsar://pulsar-primary.acme.org:6651-pulsar://pulsar-primary.acme.org:6651-0
2025-10-10 12:56:28.875 INFO  [0x16cf07000] ClientConnection:410 | [192.168.100.214:65139 -> < redacted_ip >] Connected to broker
2025-10-10 12:56:38.836 ERROR [0x16cf07000] ClientConnection:634 | [192.168.100.214:65139 -> < redacted_ip >] Connection was not established in 10000 ms, close the socket
2025-10-10 12:56:38.837 INFO  [0x16cf07000] ClientConnection:1336 | [192.168.100.214:65139 -> < redacted_ip >] Connection disconnected (refCnt: 2)
2025-10-10 12:56:38.837 INFO  [0x16cf07000] ConnectionPool:141 | Remove connection for pulsar://pulsar-primary.acme.org:6651-pulsar://pulsar-primary.acme.org:6651-0
2025-10-10 12:56:38.837 INFO  [0x16cf07000] RetryableOperation:114 | Reschedule get-partition-metadata-persistent:/< redacted_topic > for 100 ms, remaining time: 29900 ms
2025-10-10 12:56:38.837 INFO  [0x16cf07000] ClientConnection:282 | [192.168.100.214:65139 -> < redacted_ip >] Destroyed connection to pulsar://pulsar-primary.acme.org:6651-0

After switching the client to use pulsar+ssl://, the example consumer code works with no other changes.

client = pulsar.Client("pulsar+ssl://pulsar-primary.acme.org:6651")

Is this difference in behavior known and/or expected?

[merlimat]

@mattsre The use_tls is indeed deprecated setting.
In early client version, it was actually requiring to use both pulsar+ssl as well as use_tls. Later on, the flag was made redundant by inferring directly, though it was not removed to avoid compatibility issues.