{"record":{"id":"60f672e7e0a2f840","repo":"neo4j/neo4j","slug":"routing-is-not-supported-on-this-connector","errorCode":null,"errorMessage":"Routing is not supported on this connector","messagePattern":"Routing is not supported on this connector","errorType":"exception","errorClass":"CapabilityViolationStateTransitionException","httpStatus":null,"severity":"error","filePath":"community/bolt/src/main/java/org/neo4j/bolt/protocol/common/fsm/transition/negotiation/HelloStateTransition.java","lineNumber":72,"sourceCode":"    public static HelloStateTransition getInstance() {\n        return INSTANCE;\n    }\n\n    @Override\n    public StateReference process(Context ctx, HelloMessage message, ResponseHandler handler)\n            throws StateMachineException {\n        var features = message.features().stream()\n                .map(Feature::findFeatureById)\n                .filter(Objects::nonNull)\n                .toList();\n        var userAgent = message.userAgent();\n        var routingContext = message.routingContext();\n        var notificationsConfig = message.notificationsConfig();\n        var boltAgent = message.boltAgent();\n\n        if (routingContext.isServerRoutingEnabled()\n                && ctx.connection().connector().localQueryExecutionOnly()) {\n            throw new CapabilityViolationStateTransitionException(\"Routing is not supported on this connector\");\n        }\n\n        var enabledFeatures =\n                ctx.connection().negotiate(features, userAgent, routingContext, notificationsConfig, boltAgent);\n        if (!enabledFeatures.isEmpty()) {\n            var builder = ListValueBuilder.newListBuilder(enabledFeatures.size());\n            enabledFeatures.forEach(feature -> builder.add(Values.stringValue(feature.getId())));\n\n            handler.onMetadata(\"patch_bolt\", builder.build());\n        }\n\n        // TODO: Introduce dedicated handler methods?\n        handler.onMetadata(\"connection_id\", Values.stringValue(ctx.connection().id()));\n        handler.onMetadata(\"server\", Values.stringValue(\"Neo4j/\" + Version.getNeo4jVersion()));\n\n        if (ctx.connection().hasSelectedProtocolCapability(ProtocolCapability.HANDSHAKE_V2)) {\n            handler.onMetadata(\n                    \"protocol_version\",","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/neo4j/neo4j/blob/f213380f812b820a1b312e2ea52cb3d8f1931ccc/community/bolt/src/main/java/org/neo4j/bolt/protocol/common/fsm/transition/negotiation/HelloStateTransition.java#L54-L90","documentation":"Thrown by HelloStateTransition during HANDSHAKE/HELLO processing when the client's routing context has server-side routing enabled (routingContext.isServerRoutingEnabled(), i.e. a 'server-policy' routing context) while the connector answers localQueryExecutionOnly()==true. Connectors that never route (notably the Unix domain socket connector) reject the capability negotiation with CapabilityViolationStateTransitionException instead of silently degrading.","triggerScenarios":"A client connects over a local-execution-only connector (e.g. server.bolt.unix_socket_path) with a URL of the form neo4j://... or a ServerPolicy routing context, which sets the server-routing flag in the HELLO routing context.","commonSituations":"Switching a driver URL from bolt://host:7687 to neo4j://... (or to a socket address) while still connecting to the loopback connector; clustering-aware drivers defaulting to routing mode; automation scripts reused between TCP and socket endpoints.","solutions":["Use the direct scheme when connecting to local-only connectors: bolt://localhost:7687 or bolt+unix:// style endpoints instead of neo4j://.","Remove the ServerPolicy/routing context from the driver config (no 'routing' policy, no address=... server-policy parameters).","Connect over the standard TCP Bolt connector if routing (neo4j://) is genuinely required.","For the Unix socket, keep traffic to direct system-db admin sessions (see error 10)."],"exampleFix":"// before\nDriver driver = GraphDatabase.driver(\"neo4j://localhost\", authToken); // routing context -> violation\n\n// after\nDriver driver = GraphDatabase.driver(\"bolt://localhost:7687\", authToken); // direct, no routing","handlingStrategy":"validation","validationCode":"// Client-side: choose scheme by connector type\nString uri = isUnixOrLoopbackConnector ? \"bolt://localhost:7687\" : \"neo4j://host:7687\";\nDriver d = GraphDatabase.driver(uri, auth);","typeGuard":null,"tryCatchPattern":"catch (Neo4jException e) {\n    if (e.getMessage().contains(\"Routing is not supported\"))\n        throw new IllegalStateException(\"Recreate the driver with bolt:// (direct) for this endpoint\", e);\n}","preventionTips":["Map endpoint -> scheme in connection config: neo4j:// only for routing-capable TCP endpoints.","Do not attach ServerPolicy/routing contexts to socket or loopback connections.","Smoke-test each new endpoint with driver.verifyConnectivity() using the intended scheme."],"tags":["routing","protocol","driver","unix-socket","handshake"],"backgroundTag":null,"analyzedSha":"f213380f812b820a1b312e2ea52cb3d8f1931ccc","analyzedAt":"2026-08-14T15:32:33.859Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}