Neo4j "Failed to connect to ... 7687" (Bolt refused) in CI

Neo4j serves the Bolt protocol on port 7687. Until the server finishes starting and binds the connector, connection attempts are refused. In CI this is the classic race between container creation and server readiness.

What this error means

The driver or cypher-shell fails with "Failed to connect to localhost:7687 (Connection refused)" right after the container starts, then succeeds once Neo4j is up.

cypher-shell

Unable to connect to localhost:7687, ensure the database is running and that
there is a working network connection to it: Failed to establish connection in 5000ms

Common causes

The Bolt connector has not bound yet

The server is mid-startup and has not yet opened 7687, so the OS refuses the connection.

No readiness wait before the connecting step

The job runs cypher-shell or the app immediately, before Neo4j logs that it has started.

How to fix it

Poll the HTTP port, then connect on Bolt

Wait for the HTTP endpoint on 7474 to answer.
Then run a cypher-shell probe to confirm Bolt is ready.
Start the app only after both succeed.

Terminal

until cypher-shell -a bolt://127.0.0.1:7687 -u neo4j -p password "RETURN 1" >/dev/null 2>&1; do
  echo "waiting for neo4j bolt"; sleep 3
done

Add a container health check

Gate dependent steps on a health check so they only run once Neo4j is up.

.github/workflows/ci.yml

services:
  neo4j:
    image: neo4j:5
    env: { NEO4J_AUTH: neo4j/password }
    ports: ['7474:7474', '7687:7687']
    options: --health-cmd "cypher-shell -u neo4j -p password 'RETURN 1'" --health-retries 15

How to prevent it

Wait for a cypher-shell probe before connecting.
Health-check the container on the Bolt port.
Allow enough retries for first boot.