Neo4j "ServiceUnavailable ... defunct connection" in CI

By Kaveh Alemi·Latchkey

The Neo4j driver raises ServiceUnavailable when it cannot establish or keep a Bolt connection to the server. In CI the most common trigger is connecting before Neo4j finishes booting, which the driver reports as a defunct connection or failed routing.

What this error means

The driver fails with "neo4j.exceptions.ServiceUnavailable: Unable to retrieve routing information" or "Failed to read from defunct connection", clearing once the server is up.

neo4j.exceptions.ServiceUnavailable: Unable to retrieve routing information
Failed to read from defunct connection IPv4Address(('127.0.0.1', 7687))

Common causes

The server is still starting

Neo4j needs time to start the Bolt connector; connecting before "Started." in the log produces a defunct connection.

Using a routing scheme against a single instance

A neo4j:// routing URI expects routing info; a standalone CI instance may not answer routing until fully up.

How to fix it

Verify connectivity before running queries

1. Call driver.verify_connectivity() in a retry loop.
2. Sleep and retry on ServiceUnavailable.
3. Proceed only after connectivity is confirmed.

from neo4j import GraphDatabase
from neo4j.exceptions import ServiceUnavailable
import time
driver = GraphDatabase.driver("bolt://127.0.0.1:7687", auth=("neo4j", "password"))
for _ in range(30):
    try:
        driver.verify_connectivity(); break
    except ServiceUnavailable:
        time.sleep(3)

Use a direct bolt:// scheme for a single instance

For a standalone CI container, bolt:// avoids routing lookups that a non-cluster instance need not serve.

services:
  neo4j:
    image: neo4j:5
    env:
      NEO4J_AUTH: neo4j/password
    ports: ['7687:7687']
    options: --health-cmd "wget -qO- http://localhost:7474 || exit 1" --health-retries 15

How to prevent it

• Call verify_connectivity() with retries before queries.
• Use bolt:// for standalone CI instances.
• Health-check the HTTP port before connecting on Bolt.

Frequently asked questions

Related guides

References

• GitHub Actions documentation