apache/beam · error · IllegalArgumentException

Expected the Transform Service config to contain at least…

Error message

Expected the Transform Service config to contain at least one Expansion Service.

What it means

Thrown by TransformServiceConfig.parseFromYamlStream when the YAML parsed into a map but has no 'expansionservices' key, so no expansion service endpoints were configured. The transform service needs at least one expansion service address to operate.

Solutions

1. Add an 'expansionservices' key with a list of endpoint addresses to the YAML.
2. Check the key spelling is exactly lowercase 'expansionservices' (not 'expansionServices').
3. Confirm the list is non-empty and each entry is a valid host:port address.

Example fix

// before
services:
  - "localhost:12345"
// after
expansionservices:
  - "localhost:12345"

@SuppressWarnings("unchecked")
static void validateConfigKeys(String path) throws IOException {
  try (InputStream in = new FileInputStream(path)) {
    Map<Object, Object> cfg = (Map<Object, Object>) new Yaml().load(in);
    if (cfg == null || !cfg.containsKey("expansionservices")) {
      throw new IllegalArgumentException(path + " must contain an 'expansionservices' list");
    }
  }
}

try {
  config = TransformServiceConfig.parseFromYamlStream(stream);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("at least one Expansion Service")) {
    throw new IllegalArgumentException("Add 'expansionservices: [host:port, ...]' to the config YAML.", e);
  }
  throw e;
}

When it happens

Trigger: Providing a YAML config mapping that lacks 'expansionservices' (or misspells it, e.g. 'expansionServices' — key lookup is exact and case-sensitive).

Common situations: Misspelled or camelCase key instead of the exact lowercase 'expansionservices'; copying a config from old docs; forgetting the key while adding other settings.

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…
• Batch size is too large! It should be smaller or equal than
• Column delimiter should be set if headers are present.
• Column headers should be supplied when delimiter is present.
• Either Query or Table must be specified.

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

Appendix: source

Thrown at sdks/java/transform-service/src/main/java/org/apache/beam/sdk/transformservice/TransformServiceConfig.java:57

    return new AutoValue_TransformServiceConfig(expansionservices);
  }

  static TransformServiceConfig parseFromYamlStream(InputStream inputStream) {
    Yaml yaml = new Yaml();
    Map<Object, Object> config = yaml.load(inputStream);
    if (config == null) {
      throw new IllegalArgumentException(
          "Could not parse the provided YAML stream into a non-trivial TransformServiceConfig");
    }

    List<String> expansionservices = null;
    if (config.get("expansionservices") != null) {
      expansionservices = (List<String>) config.get("expansionservices");
    }

    if (expansionservices == null) {
      throw new IllegalArgumentException(
          "Expected the Transform Service config to contain at least one Expansion Service.");
    }

    return TransformServiceConfig.create(expansionservices);
  }
}

View on GitHub (pinned to 12126d8942)