neo4j/neo4j · error · PortBindException

Domain socket listen file: {} already exists.

Error message

Domain socket listen file: {} already exists.

What it means

Thrown by DomainSocketNettyConnector.onStart() when the configured Unix socket path already exists on disk and server.bolt.unix_socket_delete (BoltConnector.unix_socket_delete, default false) does not permit the server to remove it. Neo4j treats a pre-existing socket file as a potential bind hazard and refuses to start the connector with a PortBindException wrapping java.net.BindException.

Source

Thrown at community/bolt/src/main/java/org/neo4j/bolt/protocol/common/connector/netty/DomainSocketNettyConnector.java:147

        // connector as this connector is explicitly designed for maintenance purposes - lack of
        // proper routing support also means that queries on non-leader instances would likely fail
        if (!configuration.permitUserDatabaseAccess()) {
            this.registerListener(new DomainSocketRestrictionListener());
        }
    }

    @Override
    protected Class<? extends ServerChannel> channelType() {
        return transport.serverDomainSocketChannelType();
    }

    @Override
    protected void onStart() throws Exception {
        super.onStart();

        if (Files.exists(path)) {
            if (!this.configuration().deleteSocketFile()) {
                throw new PortBindException(
                        bindAddress, new BindException("Domain socket listen file: " + path + " already exists."));
            }

            try {
                Files.deleteIfExists(path);
            } catch (IOException ex) {
                throw new PortBindException(bindAddress, ex);
            }
        }
    }

    @Override
    protected void onChannelBound(Channel channel) throws PortBindException {
        try {
            Files.setPosixFilePermissions(path, configuration().socketFilePermissionMask());
        } catch (IOException ex) {
            throw new PortBindException(bindAddress, ex);
        }

View on GitHub (pinned to f213380f81)

Solutions

1. Remove the stale file manually before start: rm /var/run/neo4j/neo4j.sock (confirm no live Neo4j is using it first).
2. Set server.bolt.unix_socket_delete=true so the server cleans up stale socket files on startup.
3. If another live instance owns the file, change server.bolt.unix_socket_path for one of them instead of deleting.
4. In unit files, add ExecStartPre=/usr/bin/rm -f /var/run/neo4j/neo4j.sock as a belt-and-braces cleanup.

Example fix

# before (neo4j.conf)
server.bolt.unix_socket_delete=false

# after
server.bolt.unix_socket_delete=true

Path sock = Path.of("/var/run/neo4j/neo4j.sock");
if (Files.exists(sock) && noLiveNeo4j()) Files.deleteIfExists(sock); // before enabling the connector

When it happens

Trigger: Restarting Neo4j after an unclean shutdown (kill -9, crash, OOM) that left the stale socket file behind while server.bolt.unix_socket_delete=false (the default); two instances configured with the same server.bolt.unix_socket_path.

Common situations: First enablement of the unix socket connector on a machine where a test instance already created /var/run/neo4j/neo4j.sock; systemd service restarts after crashes; CI runners with dirty /run state between builds.

Related errors

• A file has not been specified for use with the Unix Domain S
• An error occurred while trying to bind to the socket {}
• OCSP Server stapling can only be used with JDK ssl provider
• Unsupported queue size %d for thread pool creation.
• Failed to load SSL policy for connector

AI-assisted analysis of neo4j/neo4j@f213380f81 (2026-08-14). Data as JSON: /api/errors/21319b5bd6433242. Report an issue: GitHub.