apache/beam · error · java.lang.IllegalArgumentException

Expected the path to be not null

Error message

Expected the path to be not null

What it means

Thrown by ExpansionServiceConfig.parseFromYamlStream while parsing the 'dependencies' section: each dependency entry must include a 'path' key identifying the jar/URL to stage. When a dependency map lacks 'path', the service cannot construct a Dependency and fails fast.

Solutions

1. Add the required 'path' key to every dependency entry in the YAML.
2. Fix the key spelling to exactly 'path'.
3. Remove empty map entries ({}) from the dependencies list.

Example fix

// before
dependencies:
  org.example:MyTransform:
    - paths: /jars/my.jar
// after
dependencies:
  org.example:MyTransform:
    - path: /jars/my.jar

Map<String, Object> cfg = new Yaml().load(new FileInputStream(configPath));
for (Map.Entry<String, Object> e : ((Map<String, Object>) cfg.getOrDefault("dependencies", Map.of())).entrySet()) {
  for (Object dep : (List<?>) e.getValue()) {
    if (((Map<?, ?>) dep).get("path") == null) {
      throw new IllegalStateException("Dependency for " + e.getKey() + " missing 'path'");
    }
  }
}

boolean hasPath(Object dep) { return dep instanceof Map && ((Map<?, ?>) dep).get("path") instanceof String && !((String) ((Map<?, ?>) dep).get("path")).isEmpty(); }

try {
  cfg = ExpansionServiceConfig.parseFromYamlStream(stream);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("path to be not null")) { /* fix dependencies YAML */ }
  throw e;
}

When it happens

Trigger: A YAML config file with a dependencies entry that specifies other keys (or none) but no 'path', e.g. 'dependencies:\n transform: [{}]'.

Common situations: Hand-edited config file with a typo like 'paths:' or 'file:' instead of 'path'; a list item that is an empty map; copying an example and deleting the path value.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Could not parse the provided YAML stream into a non-trivial…
• Allow list file does not exist
• Ambiguous expression type (perhaps missing quoting?)
• BigQuery temp location expected a valid 'gs://' path, but…
• Cannot set both version and timestamp.

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

Appendix: source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/ExpansionServiceConfig.java:77

    Map<String, List<Dependency>> dependencies = new HashMap<>();
    if (config.get("allowlist") != null) {
      allowList = (List<String>) config.get("allowlist");
    }

    if (config.get("dependencies") != null) {
      Map<String, List<Object>> dependenciesFromConfig =
          (Map<String, List<Object>>) config.get("dependencies");
      dependenciesFromConfig.forEach(
          (k, v) -> {
            if (v != null) {
              List<Dependency> dependenciesForTransform =
                  v.stream()
                      .map(
                          val -> {
                            Map<String, Object> depProperties = (Map<String, Object>) val;
                            String path = (String) depProperties.get("path");
                            if (path == null) {
                              throw new IllegalArgumentException(
                                  "Expected the path to be not null");
                            }
                            return Dependency.create(path);
                          })
                      .collect(Collectors.toList());
              dependencies.put(k, dependenciesForTransform);
            }
          });
    }
    return ExpansionServiceConfig.create(allowList, dependencies);
  }
}

View on GitHub (pinned to 12126d8942)