apache/beam · error · RuntimeException

please provide a neo4j config

Error message

please provide a neo4j config

What it means

Neo4jIO's buildDriver requires a driver configuration (a function providing Config / connection settings). getConfig() returned null, meaning no neo4j config provider was supplied to the connector, so it cannot construct the Neo4j Driver and throws RuntimeException.

Solutions

1. Add a driver config to the transform: .withDriverConfig(Config.builder().withoutEncryption().build()) or your tuned Config.
2. If using withDriverProviderFn, make sure it internally supplies a non-null config or rely on the default config path.
3. Check that the config supplier doesn't return null at runtime (e.g. options-based lookup failing).

Example fix

// before
Neo4jIO.<Row>read().withDriverProviderFn(providerFn)
// after
Neo4jIO.<Row>read()
  .withDriverProviderFn(providerFn)
  .withDriverConfig(Config.builder().withoutEncryption().build())

Config cfg = getConfig();
if (cfg == null) {
  throw new IllegalStateException("withDriverConfig(...) must be called before running Neo4jIO");
}

try {
  Driver d = buildDriver();
} catch (RuntimeException e) {
  if ("please provide a neo4j config".equals(e.getMessage())) {
    throw new IllegalStateException("Add .withDriverConfig(Config.builder()...build())", e);
  }
  throw e;
}

When it happens

Trigger: Using Neo4jIO.read()/write() without calling .withDriverConfig(...) (or the config supplier returns null), then running the pipeline so expand -> buildDriver executes.

Common situations: Forgetting withDriverConfig when using a custom driver provider; passing a null/empty config function in builder code; copying example pipelines and removing the config line.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• A schema was provided without a data format (or viceversa)…
• Batch size is too large! It should be smaller or equal than
• boolean cross product parameter required to explode more…
• Both a BigQuery table and a query were specified. Please…
• Both deidentification_template_name and…

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

Appendix: source

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

          useDefault);
      return builder().setHasDefaultConfig(useDefault).build();
    }

    void populateDisplayData(DisplayData.Builder builder) {
      builder.addIfNotNull(DisplayData.item("neo4j-url", getUrl()));
      builder.addIfNotNull(DisplayData.item("neo4j-username", getUsername()));
      builder.addIfNotNull(
          DisplayData.item(
              "neo4j-password", getPassword() != null ? "<provided>" : "<not-provided>"));
    }

    Driver buildDriver() {
      // Create the Neo4j Driver
      // This uses the provided Neo4j configuration along with URLs, username and password
      //
      Config config = getConfig();
      if (config == null) {
        throw new RuntimeException("please provide a neo4j config");
      }
      // We're trying to work around a subtle serialisation bug in the Neo4j Java driver.
      // The fix is work in progress.  For now, we harden our code to avoid
      // wild goose chases.
      //
      Boolean hasDefaultConfig = getProvidedValue(getHasDefaultConfig());
      if (hasDefaultConfig != null && hasDefaultConfig) {
        config = Config.defaultConfig();
      }

      // Get the list of the URI to connect with
      //
      List<URI> uris = new ArrayList<>();
      String url = getProvidedValue(getUrl());
      if (url != null) {
        try {
          uris.add(new URI(url));
        } catch (URISyntaxException e) {

View on GitHub (pinned to 12126d8942)