What causes "Routing is not supported on this connector" in neo4j/neo4j?

Use the direct scheme when connecting to local-only connectors: bolt://localhost:7687 or bolt+unix:// style endpoints instead of neo4j://.

neo4j/neo4j · error · CapabilityViolationStateTransitionException

Routing is not supported on this connector

Error message

Routing is not supported on this connector

What it means

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.

Source

Thrown at community/bolt/src/main/java/org/neo4j/bolt/protocol/common/fsm/transition/negotiation/HelloStateTransition.java:72

    public static HelloStateTransition getInstance() {
        return INSTANCE;
    }

    @Override
    public StateReference process(Context ctx, HelloMessage message, ResponseHandler handler)
            throws StateMachineException {
        var features = message.features().stream()
                .map(Feature::findFeatureById)
                .filter(Objects::nonNull)
                .toList();
        var userAgent = message.userAgent();
        var routingContext = message.routingContext();
        var notificationsConfig = message.notificationsConfig();
        var boltAgent = message.boltAgent();

        if (routingContext.isServerRoutingEnabled()
                && ctx.connection().connector().localQueryExecutionOnly()) {
            throw new CapabilityViolationStateTransitionException("Routing is not supported on this connector");
        }

        var enabledFeatures =
                ctx.connection().negotiate(features, userAgent, routingContext, notificationsConfig, boltAgent);
        if (!enabledFeatures.isEmpty()) {
            var builder = ListValueBuilder.newListBuilder(enabledFeatures.size());
            enabledFeatures.forEach(feature -> builder.add(Values.stringValue(feature.getId())));

            handler.onMetadata("patch_bolt", builder.build());
        }

        // TODO: Introduce dedicated handler methods?
        handler.onMetadata("connection_id", Values.stringValue(ctx.connection().id()));
        handler.onMetadata("server", Values.stringValue("Neo4j/" + Version.getNeo4jVersion()));

        if (ctx.connection().hasSelectedProtocolCapability(ProtocolCapability.HANDSHAKE_V2)) {
            handler.onMetadata(
                    "protocol_version",

View on GitHub (pinned to f213380f81)

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).

Example fix

// before
Driver driver = GraphDatabase.driver("neo4j://localhost", authToken); // routing context -> violation

// after
Driver driver = GraphDatabase.driver("bolt://localhost:7687", authToken); // direct, no routing

Defensive patterns

Strategy: validation

Validate before calling

// Client-side: choose scheme by connector type
String uri = isUnixOrLoopbackConnector ? "bolt://localhost:7687" : "neo4j://host:7687";
Driver d = GraphDatabase.driver(uri, auth);

Try / catch

catch (Neo4jException e) {
    if (e.getMessage().contains("Routing is not supported"))
        throw new IllegalStateException("Recreate the driver with bolt:// (direct) for this endpoint", e);
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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