neo4j/neo4j · error · UnsupportedOperationException

Authentication tokens should not contain points

Error message

Authentication tokens should not contain points

What it means

The point-value guard in auth tokens: AuthTokenValueWriter.newPoint throws UnsupportedOperationException when the HELLO auth token contains a spatial Point value. Unlike the transaction-metadata writer (which supports points), the auth-token writer rejects them too, because auth metadata must flatten to plain Java objects that the security backends can store/compare. Thrown during HELLO decoding, before authentication proceeds.

Source

Thrown at community/bolt/src/main/java/org/neo4j/bolt/protocol/common/message/decoder/util/AuthenticationMetadataUtils.java:123

        @Override
        protected Node newNodeEntityByElementId(String elementId) {
            throw new UnsupportedOperationException("Authentication tokens should not contain nodes");
        }

        @Override
        protected Relationship newRelationshipEntityById(long id) {
            throw new UnsupportedOperationException("Authentication tokens should not contain relationships");
        }

        @Override
        protected Relationship newRelationshipEntityByElementId(String elementId) {
            throw new UnsupportedOperationException("Authentication tokens should not contain relationships");
        }

        @Override
        protected Point newPoint(CoordinateReferenceSystem crs, double[] coordinate) {
            throw new UnsupportedOperationException("Authentication tokens should not contain points");
        }
    }
}

View on GitHub (pinned to f213380f81)

Solutions

Convert the Point to a primitive form before adding it to the token: {lat: p.y, lon: p.x} or a WKT string
Keep auth tokens limited to scheme/principal/credentials/realm and scalar extras
Assert token values are String/Number/Boolean before connecting

Example fix

// before
{ scheme:'basic', ..., home: pointValue }

// after
{ scheme:'basic', ..., homeLat: pointValue.y, homeLon: pointValue.x }

Defensive patterns

Strategy: validation

Validate before calling

const flat = { lat: p.y, lon: p.x, srid: p.srid };

Type guard

function isPoint(v) { return v && typeof v === 'object' && 'srid' in v; }

Try / catch

catch (e) { if (/tokens should not contain points/i.test(e.message)) { serialize point as lat/lon numbers and reconnect; } else throw e; }

Prevention

Remember auth tokens are stricter than tx_metadata: points allowed in one, rejected in the other

When it happens

Trigger: An authToken map in HELLO contains a Bolt Point struct (e.g. a location value from a previous query result reused in the token), so flattening dispatches to the guarded newPoint instead of Values.pointValue.

Common situations: Apps storing 'last known location' points and attaching them to auth tokens; Custom clients reusing arbitrary result values as token extras; Test harnesses fuzzing token maps with all value types

Understand the failure class

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

Related errors

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