Pulsar "Connection refused" on port 6650 before broker ready in CI

The Pulsar client could not open the binary protocol port 6650 because the broker is still starting. Pulsar standalone boots BookKeeper, ZooKeeper, and the broker in sequence, so the binary port opens several seconds after the container starts.

What this error means

The client fails with "Connection refused: localhost/127.0.0.1:6650" or "Could not connect to broker" on the first producer or consumer creation.

Terminal

org.apache.pulsar.client.api.PulsarClientException:
java.net.ConnectException: Connection refused: localhost/127.0.0.1:6650

Common causes

The standalone broker is still booting

Pulsar standalone starts several components before the broker opens 6650, so early connects are refused.

The binary port is not mapped

Only the admin port (8080) is published, or the wrong port is used, so the binary protocol connection finds nothing.

How to fix it

Wait for the admin endpoint before connecting

Poll the broker health admin API until it returns before creating clients.

Terminal

until curl -sf http://localhost:8080/admin/v2/brokers/health; do
  echo "waiting for pulsar"; sleep 3
done

Map both the binary and admin ports

Publish 6650 for clients and 8080 for the admin/health check.

.github/workflows/ci.yml

services:
  pulsar:
    image: apachepulsar/pulsar:3.2.0
    command: ["bin/pulsar", "standalone"]
    ports: ['6650:6650', '8080:8080']

How to prevent it

Gate clients on the broker health admin endpoint.
Publish both 6650 and 8080 from the Pulsar service.
Allow a generous wait; standalone startup is multi-component.