Introduction

When Neo4j authentication "doesn't work" in Docker, the problem is usually configuration state rather than the login command itself. The most common causes are a bad NEO4J_AUTH value, an existing data volume that preserves old credentials, or connecting to the wrong service endpoint. The key detail many people miss is that the initial password setup is typically applied only on first startup of a fresh data directory.

Set NEO4J_AUTH Correctly

A standard docker run example looks like this:

1docker run --name neo4j-test \
2  -p 7474:7474 -p 7687:7687 \
3  -e NEO4J_AUTH=neo4j/secret123 \
4  neo4j:5

The format is username/password, and for the default admin user that normally means neo4j/somePassword.

If the environment variable is malformed, Neo4j may refuse startup or keep using existing auth data. Always inspect the container logs after launch:

docker logs neo4j-test

That usually tells you whether authentication was initialized, rejected, or skipped.

Existing Volumes Often Preserve Old Credentials

This is the most common reason the configured password seems ignored. If the container mounts a persistent /data volume, the database already contains auth state from a previous run.

Example:

1docker run --name neo4j-test \
2  -p 7474:7474 -p 7687:7687 \
3  -v neo4j_data:/data \
4  -e NEO4J_AUTH=neo4j/secret123 \
5  neo4j:5

If neo4j_data already existed with a different password, changing NEO4J_AUTH in a later run will not reset it automatically.

For a disposable local test, remove the volume and start fresh:

docker rm -f neo4j-test
docker volume rm neo4j_data

Then recreate the container with the new password.

For persistent environments, change the password through Neo4j itself instead of expecting the environment variable to overwrite existing auth state.

Confirm You Are Connecting to the Right Endpoint

Neo4j exposes two common ports:

• '7474 for the HTTP browser UI'
• '7687 for the Bolt protocol used by most drivers'

A login problem can actually be a protocol or connection problem if the client is pointed at the wrong port. For example, a Bolt driver should not be aimed at the browser port.

Python driver example:

1from neo4j import GraphDatabase
2
3driver = GraphDatabase.driver(
4    "bolt://localhost:7687",
5    auth=("neo4j", "secret123")
6)
7
8with driver.session() as session:
9    result = session.run("RETURN 1 AS value")
10    print(result.single()["value"])

If this fails, compare it against browser login on http://localhost:7474 to determine whether the issue is credentials or client connection settings.

Use Docker Compose Carefully

The same rules apply in Compose:

1services:
2  neo4j:
3    image: neo4j:5
4    ports:
5      - "7474:7474"
6      - "7687:7687"
7    environment:
8      NEO4J_AUTH: neo4j/secret123
9    volumes:
10      - neo4j_data:/data
11
12volumes:
13  neo4j_data:

If login does not change after updating the password in the Compose file, the volume is the first place to look. The container definition may be new while the stored database state is old.

Distinguish Password Initialization from Password Change

NEO4J_AUTH is best thought of as initial bootstrap configuration. Once the database has started and persisted auth data, password management becomes an application-level concern. That means:

• use the browser or driver to change password in an existing instance
• use fresh volumes when you want clean bootstrap behavior
• do not expect restart-time environment changes to rewrite persisted auth automatically

This distinction explains a large percentage of "Docker ignored my password" reports.

Common Pitfalls

• Changing NEO4J_AUTH while reusing an old /data volume and expecting the password to reset.
• Typing the environment variable in the wrong username/password format.
• Connecting a Bolt driver to the HTTP browser port instead of port 7687.
• Looking only at the Compose file and not at persisted container volumes.
• Treating password bootstrap and password rotation as the same mechanism.

Summary

• Neo4j Docker authentication failures are often caused by persisted auth state, not by the login command itself.
• 'NEO4J_AUTH is mainly for first startup of a fresh data directory.'
• Existing /data volumes preserve prior credentials until you change them explicitly or recreate the volume.
• Verify that clients use the correct protocol and port.
• Check container logs early because they usually reveal whether auth initialization actually happened.