Couchbase "connection refused" on port 8091 (cluster not ready) in CI

Couchbase exposes its management API and UI on port 8091. A fresh container must finish starting and be initialized (cluster set up, services configured) before clients can use it. Connecting too early gives "connection refused" on 8091.

What this error means

An SDK or curl call to 8091 fails with "connection refused", or the SDK reports it cannot bootstrap against the cluster, until the node is started and initialized.

curl: (7) Failed to connect to 127.0.0.1 port 8091 after 0 ms:
Connection refused

Common causes

The management service has not started

Couchbase needs time to start its services; until 8091 is bound, the management API refuses connections.

The cluster was never initialized

A fresh Couchbase node must be initialized (cluster-init, bucket creation) before the SDK can bootstrap, even once 8091 answers.

How to fix it

Wait for the management API to answer

1. Poll the /pools endpoint on 8091 until it responds.
2. Then run couchbase-cli cluster-init to initialize.
3. Create the bucket before tests bootstrap the SDK.

until curl -fs http://127.0.0.1:8091/pools >/dev/null; do
  echo "waiting for couchbase management api"; sleep 3
done

Initialize the cluster and bucket in setup

Run cluster-init and bucket-create so the SDK has something to bootstrap against.

couchbase-cli cluster-init -c 127.0.0.1 \
  --cluster-username Administrator --cluster-password password \
  --services data,index,query --cluster-ramsize 512

How to prevent it

• Poll /pools on 8091 before initializing.
• Run cluster-init and bucket-create before tests.
• Allow generous startup time for first boot.

Related guides