Neo4j "Neo.ClientError.Security.Unauthorized" authentication failure in CI

By Daniel Zoghalchali·Latchkey

Neo4j rejects a connection with Neo.ClientError.Security.Unauthorized when the supplied username or password is wrong. In CI this usually means the driver credentials do not match NEO4J_AUTH, or the default password change requirement was not handled.

What this error means

Connecting fails with "Neo.ClientError.Security.Unauthorized: The client is unauthorized due to authentication failure." even though the Bolt port is reachable.

neo4j.exceptions.AuthError: {code: Neo.ClientError.Security.Unauthorized}
{message: The client is unauthorized due to authentication failure.}

Common causes

Driver credentials do not match NEO4J_AUTH

The container was started with one password but the test connects with another (or with the unchanged default neo4j/neo4j).

The default password change was required

Without setting NEO4J_AUTH, Neo4j may require changing the initial password before queries are allowed.

How to fix it

Set NEO4J_AUTH and use the same credentials

1. Define NEO4J_AUTH=neo4j/<password> on the service container.
2. Use the exact same user and password in the driver.
3. Avoid relying on the default neo4j/neo4j.

services:
  neo4j:
    image: neo4j:5
    env:
      NEO4J_AUTH: neo4j/testpassword
    ports: ['7687:7687']

Pass matching auth from a secret in the app

Read the same credentials in the app so the driver and container agree.

driver = GraphDatabase.driver(
    "bolt://127.0.0.1:7687", auth=("neo4j", "testpassword"))

How to prevent it

• Set NEO4J_AUTH explicitly and reuse it everywhere.
• Keep credentials in CI secrets, not literals scattered around.
• Do not depend on the default password.

Frequently asked questions

Related guides

References

• GitHub Actions documentation