apache/beam · error · RuntimeException

Error creating URI from URL '" + url + "'

Error message

Error creating URI from URL '" + url + "'

What it means

buildDriver parses the single URL given via .withUrl(...) into a java.net.URI. If the string is not a syntactically valid URI (URISyntaxException), it wraps the failure in a RuntimeException with the offending URL. The Neo4j driver cannot be built without at least one valid routing/bolt URI.

Solutions

1. Use a fully qualified scheme URL: .withUrl("neo4j://hostname:7687") or bolt://hostname:7687.
2. Trim whitespace and remove stray quotes/brackets from the URL before passing it.
3. Validate locally: new URI(url) in a unit test, or pre-validate with URI.create and catch IllegalArgumentException early.
4. If the URL comes from options/env, log or fail fast at setup with a clear message when the placeholder is unresolved.

Example fix

// before
.withUrl("localhost:7687")
// after
.withUrl("neo4j://localhost:7687")

String url = getProvidedValue(getUrl());
if (url != null) {
  try { new URI(url); } catch (URISyntaxException e) {
    throw new IllegalArgumentException("neo4j url must include a scheme, e.g. neo4j://host:7687, got: " + url);
  }
}

static boolean isValidNeo4jUrl(String url) {
  try { new java.net.URI(url); return url.startsWith("neo4j") || url.startsWith("bolt"); }
  catch (Exception e) { return false; }
}

try {
  pipeline.apply(Neo4jIO.read()...);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Error creating URI from URL")) {
    throw new IllegalArgumentException("Fix the neo4j URL: include scheme neo4j:// or bolt://");
  }
  throw e;
}

When it happens

Trigger: Calling .withUrl("localhost:7687") or withUrl("http://myhost") etc. — missing the neo4j://, neo4j+s://, bolt:// scheme, or containing spaces/illegal characters — during expand -> buildDriver.

Common situations: Typing the host without the bolt:// or neo4j:// scheme; pasting an HTTP browser URL instead of the bolt address; environment-specific placeholders like ${NEO4J_URL} left unresolved; trailing whitespace or quotes from config files.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Error creating URI '" + providedUrl + "' from a list of " +…
• Error mapping Neo4J result
• error parsing S3 uri
• Error writing " + unwindList.size() + " rows to Neo4j with…
• MongoDb location must be in the following format…

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

Appendix: source

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

      }
      // 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) {
          throw new RuntimeException("Error creating URI from URL '" + url + "'", e);
        }
      }
      List<String> providedUrls = getProvidedValue(getUrls());
      if (providedUrls != null) {
        for (String providedUrl : providedUrls) {
          try {
            uris.add(new URI(providedUrl));
          } catch (URISyntaxException e) {
            throw new RuntimeException(
                "Error creating URI '"
                    + providedUrl
                    + "' from a list of "
                    + providedUrls.size()
                    + " URLs",
                e);
          }
        }
      }

View on GitHub (pinned to 12126d8942)