"Neo.ClientError.Security.Unauthorized": Driver does not retry authentication after transient failure

Direct answer

No. Do not implement a generic retry for Neo.ClientError.Security.Unauthorized. The Neo4j Bolt drivers classify Unauthorized as non-retryable and will not re-attempt the authentication exchange, even after a TCP reconnect. Retrying blindly risks account lockout and masks permanent credential problems.

Application-level retry is only reasonable after you have evidence that the failure is transient and your auth provider allows retries. In the absence of that evidence the safe default is zero retries: fail fast, surface the error, and require operator intervention.

Confirmed facts vs likely explanation

Confirmed

• The driver does not auto-retry authentication on Neo.ClientError.Security.Unauthorized. Session state is lost after the error and pending transactions fail.
• There is no built-in backoff or retry configuration for authentication errors in the driver. Retry policies apply to transient transport and transaction errors, not to Unauthorized.
• A new session must be created to attempt authentication again. Reusing the same session will not recover.

Likely but unverified

• Brief server overload or momentary auth-service unavailability can surface as Unauthorized in practice. Documentation does not clearly distinguish recoverable auth glitches from permanent credential failures, which is why integrators are uncertain.
• Token expiration during long-running sessions can also present as Unauthorized. This is application-specific and depends on the auth provider.

How to decide transient vs permanent

Observable signs that point to permanent credential failure:

• Failure is consistent across new sessions and new connections.
• Server logs show "Authentication failed" for the user with the same principal and no service errors.
• Immediate success when credentials are changed or tested with neo4j-shell/neo4j-admin.

Observable signs that suggest transient conditions:

• Failure is intermittent and succeeds on an immediate retry with a fresh session.
• Server logs show auth service timeouts, connection pool exhaustion, or "Auth service temporarily unavailable" around the same time.
• The error occurs only under load spikes and not in idle tests.

Safe steps if you must handle this case

1. Do not retry on the same session. Catch Neo.ClientError.Security.Unauthorized, close the session, and create a new session for any retry attempt.
2. Limit retries to a small, bounded number with exponential backoff and jitter. A common conservative starting point is 0 retries by default, and at most 1-2 retries with backoff only when you have confirmed transient signals.
3. Never retry with the same credentials if you suspect they are invalid. Log the error code, server address, timestamp, and session id for diagnostics.
4. Separate auth errors from transport errors in your retry policy. Retry transport errors; do not retry Unauthorized unless explicitly allowed by your auth provider policy.

How many attempts are safe depends on your auth provider's rate limits and lockout policy. Without that information the only safe recommendation is no retry.

Missing diagnostic detail that changes the recommendation: What authentication mechanism and lockout policy is in use, e.g., native Neo4j user/password with account lockout, LDAP, or short-lived tokens with refresh? The retry strategy and safe attempt count differ materially between them.