ArangoDB "connection refused" on port 8529 (service not ready) in CI

By Kaveh Alemi·Latchkey

ArangoDB serves its HTTP API on port 8529. The container must finish starting (initialize the system database, apply root auth) before it accepts requests. A driver that connects immediately hits "connection refused" or ECONNREFUSED on 8529.

What this error means

The driver or curl fails with "connect ECONNREFUSED 127.0.0.1:8529" or "Connection refused" right after the container starts, clearing once ArangoDB is ready.

Error: connect ECONNREFUSED 127.0.0.1:8529
    at TCPConnectWrap.afterConnect [as oncomplete]

Common causes

The HTTP API has not bound yet

ArangoDB logs "ready for business" only after startup; before that, 8529 refuses connections.

No readiness probe before the connecting step

The job connects as soon as the container exists instead of waiting for the API to answer.

How to fix it

Poll the version endpoint until it answers

1. Curl /_api/version on 8529 until it returns.
2. Pass the root credentials if auth is enabled.
3. Run setup and tests only after it succeeds.

until curl -fs -u root:password http://127.0.0.1:8529/_api/version >/dev/null; do
  echo "waiting for arangodb"; sleep 2
done

Add a container health check

Gate dependent steps on the version endpoint so they only run once ArangoDB is up.

services:
  arangodb:
    image: arangodb:3.12
    env: { ARANGO_ROOT_PASSWORD: password }
    ports: ['8529:8529']
    options: --health-cmd "curl -f http://localhost:8529/_api/version || exit 1" --health-retries 12

How to prevent it

• Probe /_api/version before connecting.
• Set ARANGO_ROOT_PASSWORD and use it consistently.
• Allow retries for first boot.

Frequently asked questions

Related guides

References

• GitHub Actions documentation