apache/beam · error · RuntimeException

please provide a driver provider

Error message

please provide a driver provider

What it means

Neo4JIO.Read/Write's expand requires a driver provider function (withDriverProviderFn) that knows how to create the Neo4j Driver in workers. When it is null at expansion time, the pipeline cannot be built and a RuntimeException "please provide a driver provider" is thrown.

Source

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

      }

      TransactionConfig transactionConfig = getTransactionConfig();
      if (transactionConfig == null) {
        transactionConfig = TransactionConfig.empty();
      }

      Boolean writeTransaction = getProvidedValue(getWriteTransaction());
      if (writeTransaction == null) {
        writeTransaction = Boolean.FALSE;
      }

      Boolean logCypher = getProvidedValue(getLogCypher());
      if (logCypher == null) {
        logCypher = Boolean.FALSE;
      }

      if (driverProviderFn == null) {
        throw new RuntimeException("please provide a driver provider");
      }
      if (rowMapper == null) {
        throw new RuntimeException("please provide a row mapper");
      }
      if (parametersFunction == null) {
        parametersFunction = t -> Collections.emptyMap();
      }

      ReadFn<ParameterT, OutputT> readFn =
          new ReadFn<>(
              driverProviderFn,
              sessionConfig,
              transactionConfig,
              cypher,
              rowMapper,
              parametersFunction,
              writeTransaction,
              logCypher);

View on GitHub (pinned to 12126d8942)

Solutions

1. Add a driver provider: .withDriverProviderFn(ignored -> GraphDatabase.driver(uri, AuthTokens.basic(user, password))).
2. Alternatively supply URL/username/password via withUrl/withUsername/withPassword plus withDriverConfig so the default provider path can build the driver.
3. Verify the builder chain: ensure withDriverProviderFn is called on the same instance (builders return new objects if misused).
4. Reuse Neo4jIO.readConfiguration()/writeConfiguration() helpers that assemble all required providers consistently.

Example fix

// before
Neo4jIO.<Row>read().withCypher("MATCH (n) RETURN n")
// after
Neo4jIO.<Row>read()
  .withCypher("MATCH (n) RETURN n")
  .withDriverProviderFn(opts -> GraphDatabase.driver("neo4j://localhost:7687", AuthTokens.basic("neo4j", pass)))

Neo4jIO.Read<Row> read = Neo4jIO.read();
if (read == null || !isConfigured(read)) {
  throw new IllegalStateException("Call .withDriverProviderFn(...) (or withUrl/username/password) before running");
}

try {
  pipeline.apply(Neo4jIO.read()...);
} catch (RuntimeException e) {
  if ("please provide a driver provider".equals(e.getMessage())) {
    throw new IllegalStateException("Neo4jIO requires withDriverProviderFn or URL+credentials configuration");
  }
  throw e;
}

When it happens

Trigger: Building a Neo4jIO.read()/write() transform without calling .withDriverProviderFn(...) (and no default is in effect) before running the pipeline.

Common situations: Omitting driver setup while specifying only cypher/parameters; refactoring that dropped the withDriverProviderFn call; confusing Neo4jIO with other connectors that default-construct drivers; conditional builder code that never sets the provider on some branch.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• The pipeline has not been run.
• The pipeline contains abandoned PTransform(s).
• .exceptionsVia() is required
• PCollections come from different Pipelines
• PCollections come from different Pipelines

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