{"record":{"id":"21319b5bd6433242","repo":"neo4j/neo4j","slug":"domain-socket-listen-file-already-exists","errorCode":null,"errorMessage":"Domain socket listen file: {} already exists.","messagePattern":"Domain socket listen file: (.+?) already exists\\.","errorType":"exception","errorClass":"PortBindException","httpStatus":null,"severity":"error","filePath":"community/bolt/src/main/java/org/neo4j/bolt/protocol/common/connector/netty/DomainSocketNettyConnector.java","lineNumber":147,"sourceCode":"        // connector as this connector is explicitly designed for maintenance purposes - lack of\n        // proper routing support also means that queries on non-leader instances would likely fail\n        if (!configuration.permitUserDatabaseAccess()) {\n            this.registerListener(new DomainSocketRestrictionListener());\n        }\n    }\n\n    @Override\n    protected Class<? extends ServerChannel> channelType() {\n        return transport.serverDomainSocketChannelType();\n    }\n\n    @Override\n    protected void onStart() throws Exception {\n        super.onStart();\n\n        if (Files.exists(path)) {\n            if (!this.configuration().deleteSocketFile()) {\n                throw new PortBindException(\n                        bindAddress, new BindException(\"Domain socket listen file: \" + path + \" already exists.\"));\n            }\n\n            try {\n                Files.deleteIfExists(path);\n            } catch (IOException ex) {\n                throw new PortBindException(bindAddress, ex);\n            }\n        }\n    }\n\n    @Override\n    protected void onChannelBound(Channel channel) throws PortBindException {\n        try {\n            Files.setPosixFilePermissions(path, configuration().socketFilePermissionMask());\n        } catch (IOException ex) {\n            throw new PortBindException(bindAddress, ex);\n        }","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/neo4j/neo4j/blob/f213380f812b820a1b312e2ea52cb3d8f1931ccc/community/bolt/src/main/java/org/neo4j/bolt/protocol/common/connector/netty/DomainSocketNettyConnector.java#L129-L165","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the stale file manually before start: rm /var/run/neo4j/neo4j.sock (confirm no live Neo4j is using it first).","Set server.bolt.unix_socket_delete=true so the server cleans up stale socket files on startup.","If another live instance owns the file, change server.bolt.unix_socket_path for one of them instead of deleting.","In unit files, add ExecStartPre=/usr/bin/rm -f /var/run/neo4j/neo4j.sock as a belt-and-braces cleanup."],"exampleFix":"# before (neo4j.conf)\nserver.bolt.unix_socket_delete=false\n\n# after\nserver.bolt.unix_socket_delete=true","handlingStrategy":"validation","validationCode":"Path sock = Path.of(\"/var/run/neo4j/neo4j.sock\");\nif (Files.exists(sock) && noLiveNeo4j()) Files.deleteIfExists(sock); // before enabling the connector","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set server.bolt.unix_socket_delete=true on hosts that may crash or be kill -9'd.","Or add ExecStartPre=/usr/bin/rm -f <socket> in the systemd unit.","Never point two instances at the same socket path."],"tags":["unix-socket","startup","filesystem","config"],"backgroundTag":null,"analyzedSha":"f213380f812b820a1b312e2ea52cb3d8f1931ccc","analyzedAt":"2026-08-14T15:32:33.859Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}