Gremlin JavaScript Driver for Apache TinkerPop

Common errors

• Error: Server error (no request information): Invalid OpProcessor requested [null] (499)

  cause This error typically indicates a mismatch in the serialization configuration between the Gremlin client and the Gremlin Server, or the client attempting an operation not supported by the server's configured OpProcessors.
  fix Ensure the Gremlin Server is configured with the expected serializers (e.g., GraphSON3 or GraphBinary) and that the client's `mimeType` option in `DriverRemoteConnection` matches. For specific graph providers like Azure Cosmos DB, ensure necessary authentication and specific `mimeType` settings are applied.

• WebSocket connection to 'ws://localhost:8182/gremlin' failed: WebSocket is closed before the connection is established.

  cause The Gremlin Server is not running, is inaccessible at the specified URL, or a firewall is blocking the connection.
  fix Verify that your Gremlin Server is running and listening on the correct host and port. Check network connectivity and firewall rules. Ensure the `gremlinServerUrl` in your client code is accurate.

• TypeError: g.V is not a function

  cause The `g` object (GraphTraversalSource) was not correctly initialized, or the `withRemote` method was not properly used to attach a connection.
  fix Ensure `g` is correctly initialized by chaining `AnonymousTraversalSource.traversal().withRemote(connection)` after establishing a `DriverRemoteConnection`. This pattern creates the fluent traversal source.

• Error: AnySerializer.deserialize(...): unknown {type_code}

  cause A serialization error occurred during deserialization of a response from the Gremlin Server, often indicating a data type that the client's current serializer does not understand or a mismatch in Graph Binary/GraphSON versions.
  fix This can happen with complex data types or specific traversal steps (like `profile()`) not fully supported by the client's default serializer or the remote graph's capabilities. Check compatibility between your Gremlin driver version, Gremlin Server version, and specific graph database. For AWS Neptune, this error can appear with `profile()` and `explain()` steps.

Warnings

• breaking Older versions of the `gremlin` driver (pre-TinkerPop 3.3.3) did not support GraphSON3, which became the default serialization format for Gremlin Server 3.3+. This led to serialization errors. The current driver (v3.8.1) uses GraphBinary as its default serialization. Ensure your Gremlin Server and client use compatible serialization protocols.
  Fix: Upgrade to `gremlin` version 3.3.3 or newer. If using an older server with a newer client, explicitly configure the `mimeType` in `DriverRemoteConnection` options to `application/vnd.gremlin-v2.0+json` on the client side, and ensure the server is configured to use GraphSON2.
• gotcha Gremlin operations with the `gremlin` driver are inherently transactional on the server side: each bytecode-based request constitutes a single transaction (commit on success, rollback on failure). Extending transactions over multiple requests typically requires using sessions with script-based submissions, which is generally not recommended due to portability, security, and future deprecation concerns.
  Fix: Design your graph mutations to be idempotent where possible. For complex multi-step updates, consider using server-side transactions if your graph database supports them, or restructure your traversals to fit within single bytecode requests. Avoid relying on explicit client-side transaction management that spans multiple requests unless using Gremlin Server sessions, which should be done with caution.
• gotcha When querying AWS Neptune, the `profile()` and `explain()` traversal steps may fail or return incomplete results when using Graph Binary serialization due to Neptune's specific query optimization.
  Fix: For query profiling and explanation on AWS Neptune, prefer using Neptune's dedicated `/profile` and `/explain` APIs instead of the Gremlin `profile()` and `explain()` steps.
• gotcha Performing full graph scans with `g.V().count()` can be very resource-intensive on large graph databases, as it typically forces the traversal to visit all vertices across all partitions. This can lead to performance degradation.
  Fix: Avoid `g.V().count()` for general size checks on large production graphs. Instead, use more targeted traversals, maintain a separate count in an external system, or leverage specific graph database features for estimating graph size if available. Use indexed traversals (e.g., `g.V().hasLabel('person').count()`) when counting specific subsets.
• breaking The `gremlin` package has increased its minimum Node.js version requirement over time. As of TinkerPop 3.8.0, the minimum supported Node.js version is 20. Using older Node.js versions will result in compatibility issues.
  Fix: Ensure your Node.js environment is running version 20 or higher to maintain compatibility with `gremlin` 3.8.x and future releases.

Install

• npm install gremlin npm
• yarn add gremlin yarn
• pnpm add gremlin pnpm

Imports

• Client
  wrong:

  import { Client } from 'gremlin';

  correct:

  import { Client } from 'gremlin/lib/driver/client';

  The Client class is typically imported from its specific driver path for direct WebSocket client interactions, while the top-level 'gremlin' import groups several modules. Named imports are standard for ESM.
• DriverRemoteConnection
  wrong:

  const DriverRemoteConnection = require('gremlin').driver.DriverRemoteConnection;

  correct:

  import { DriverRemoteConnection } from 'gremlin/lib/driver/driver-remote-connection';

  Prior to TinkerPop 3.3.3, `DriverRemoteConnection` was not properly exported from the main `gremlin` module, requiring a deep import. While fixed, specific path import remains a robust pattern. CommonJS `require` is also shown as a legacy usage.
• process.AnonymousTraversalSource.traversal
  wrong:

  import { traversal } from 'gremlin';
  const g = traversal().withRemote(connection);

  correct:

  import { AnonymousTraversalSource } from 'gremlin/lib/process/anonymous-traversal-source';
  const g = AnonymousTraversalSource.traversal().withRemote(connection);

  The traversal source `g` is typically instantiated from `AnonymousTraversalSource.traversal()`. Direct top-level import of `traversal` is not the standard pattern. Using `g` is a convention for the graph traversal source.
• statics.P
  wrong:

  import { P } from 'gremlin';

  correct:

  import { statics } from 'gremlin/lib/process/traversal';
  const { P } = statics;

  `P` (predicates like `eq`, `gt`, `lt`) and other traversal statics are grouped under `statics` within the `process/traversal` module.

Quickstart

This quickstart demonstrates how to establish a connection to a Gremlin Server, create a graph traversal source, execute a simple vertex count, add a new vertex with properties, and then count specific vertices, showcasing fundamental Gremlin operations.

import { Client } from 'gremlin/lib/driver/client';
import { DriverRemoteConnection } from 'gremlin/lib/driver/driver-remote-connection';
import { Graph } from 'gremlin/lib/structure/graph';
import { AnonymousTraversalSource } from 'gremlin/lib/process/anonymous-traversal-source';

const gremlinServerUrl = process.env.GREMLIN_SERVER_URL ?? 'ws://localhost:8182/gremlin';

async function runGremlinQuery() {
  let connection: DriverRemoteConnection | null = null;
  try {
    // Establish a remote connection to the Gremlin Server
    connection = new DriverRemoteConnection(gremlinServerUrl);
    
    // Create a GraphTraversalSource (g) for fluent Gremlin traversals
    const g = AnonymousTraversalSource.traversal().withRemote(connection);

    // Execute a simple traversal: count all vertices
    const vertexCount = await g.V().count().next();
    console.log(`Number of vertices in the graph: ${vertexCount.value}`);

    // Add a new vertex and retrieve it
    const newVertex = await g.addV('person').property('name', 'Alice').next();
    console.log(`Added vertex with ID: ${newVertex.value.id} and label: ${newVertex.value.label}`);

    // Count all 'person' vertices
    const personCount = await g.V().hasLabel('person').count().next();
    console.log(`Number of 'person' vertices: ${personCount.value}`);

  } catch (err) {
    console.error('Error during Gremlin traversal:', err);
  } finally {
    if (connection) {
      await connection.close();
      console.log('Gremlin connection closed.');
    }
  }
}

runGremlinQuery();