neo4j/neo4j · warning · ClientTimeoutException

Terminated connection '%s' (%s) as the client failed to auth

Error message

Terminated connection '%s' (%s) as the client failed to authenticate within %d ms.

What it means

Thrown by AuthenticationTimeoutHandler.authTimerEnded when the unauthenticated-connection deadline expires and no request was ever received (requestReceived is false). The server closes the channel and raises ClientTimeoutException — deliberately a client-attributed severity, since the client opened a Bolt connection and never sent HELLO/LOGON within internal.server.bolt.unauth_connection_timeout (default 30s).

Source

Thrown at community/bolt/src/main/java/org/neo4j/bolt/protocol/common/handler/AuthenticationTimeoutHandler.java:93

        }

        this.connection.memoryTracker().releaseHeap(AuthenticationTimeoutHandler.SHALLOW_SIZE);
    }

    protected void authTimerEnded(ChannelHandlerContext ctx) throws Exception {
        ctx.close();

        if (requestReceived) {
            throw new BoltConnectionFatality(
                    format(
                            "Terminated connection '%s' (%s) as the server failed to handle an authentication request within %d ms.",
                            this.connection.id(), ctx.channel(), timeout.toMillis()),
                    null);
        }

        // throw ClientTimeoutException instead of BoltConnectionFatality as we do not consider
        // client induced errors to be as severe as server caused timeouts
        throw new ClientTimeoutException(format(
                "Terminated connection '%s' (%s) as the client failed to authenticate within %d ms.",
                this.connection.id(), ctx.channel(), timeout.toMillis()));
    }

    public void setRequestReceived(boolean requestReceived) {
        this.requestReceived = requestReceived;
    }
}

View on GitHub (pinned to f213380f81)

Solutions

1. Point health checks at a real Bolt handshake (drivers' verifyConnectivity) or the HTTP status endpoints instead of bare TCP connects.
2. If probes must connect, expect this INFO-level timeout in logs and filter it — it is by-design protection, not a fault.
3. Confirm clients complete HELLO promptly (current driver versions; no TLS/provider mismatch that stalls pre-auth).
4. As a workaround for slow-to-start clients, raise internal.server.bolt.unauth_connection_timeout — but the default 30s is ample for real drivers.

Example fix

# before: LB does a bare TCP check on bolt port, logs fill with timeouts
listen 7687;

# after: check with an actual handshake or use HTTP status
# e.g. use GET on the server's HTTP endpoint (7474) for liveness instead of a raw TCP open on 7687

// health checks: perform a real handshake instead of a bare TCP connect
try (Driver d = GraphDatabase.driver("bolt://host:7687", AuthTokens.none())) { d.verifyConnectivity(); } // or use HTTP status endpoint

When it happens

Trigger: A TCP connection is opened to the Bolt port and no HELLO follows for 30s: port scanners and health checks that only connect, load balancer probes, clients stuck before handshake (blocked on DNS/TLS setup), or leaked driver connections that were never authenticated.

Common situations: LB/tcp health checks configured against 7687 without sending a Bolt handshake; monitoring probes; firewall middleboxes opening verification connections; clients whose first message blocks (e.g. TLS negotiation mismatch with a non-TLS probe).

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Terminated connection '%s' (%s) as the server failed to hand
• Message has exceeded maximum permitted complexity of {} leve
• Message has exceeded maximum permitted complexity of {} elem
• Authentication tokens should not contain nodes
• Authentication tokens should not contain relationships

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