apache/beam · error · RuntimeException

neo4j session was not initialized correctly

Error message

neo4j session was not initialized correctly

What it means

ReadFn.processElement checks that the lazily initialized Neo4j session inside the driverSession holder is non-null before running the read/write transaction. A null session means the @Setup/start bundle initialization failed to create a session (e.g. driver creation problem or state not initialized for this worker), so the read cannot proceed.

Solutions

1. Ensure the standard ReadFn/Neo4jIO lifecycle is used (let Beam call @Setup) rather than manually instantiating the DoFn.
2. If subclassing, always call super / buildDriverSession() and never assign session to null.
3. Retry the bundle; if reproducible, inspect worker logs for earlier driver-creation failures that left session unset.

if (driverSession.session == null) { throw new IllegalStateException("session not initialized; ensure Beam lifecycle (@Setup) ran"); }

When it happens

Trigger: driverSession.session is null at transaction time — typically because session initialization silently produced null, a worker reused a DoFn instance whose setup path didn't run/complete, or a custom subclass overrode initialization.

Common situations: Custom DoFn subclasses that bypass buildDriverSession; test harnesses invoking processElement without Setup; runner state issues after worker restart/reuse.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Error mapping Neo4J result
• Error writing " + unwindList.size() + " rows to Neo4j with…
• Failed to initialize cryptography libraries needed for…
• null driver given by driver provider
• please provide a parameters function

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/43d0ce3a9e55565c. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/neo4j/src/main/java/org/apache/beam/sdk/io/neo4j/Neo4jIO.java:847

            return count;
          };

      if (logCypher) {
        String parametersString = getParametersString(parametersMap);

        String readWrite = writeTransaction ? "write" : "read";
        LOG.info(
            "Starting a {} transaction for cypher: {}, parameters: {}",
            readWrite,
            cypher,
            parametersString);
      }

      // There are 2 ways to do a transaction on Neo4j: read or write
      // It's important that the right type is selected, especially in clustered configurations.
      //
      if (driverSession.session == null) {
        throw new RuntimeException("neo4j session was not initialized correctly");
      } else {
        final Long count;
        if (writeTransaction) {
          count = driverSession.session.writeTransaction(transactionWork, transactionConfig);
        } else {
          count = driverSession.session.readTransaction(transactionWork, transactionConfig);
        }
        LOG.debug("Retrieved {} elements from Neo4J", count);
      }
    }
  }

  /**
   * Wraps a {@link DriverConfiguration} to provide a {@link Driver}.
   *
   * <p>At most a single {@link Driver} instance will be constructed during pipeline execution for
   * each unique {@link DriverConfiguration} within the pipeline.
   */

View on GitHub (pinned to 12126d8942)