apache/beam · error · IllegalArgumentException

Unknown distribution type

Error message

Unknown distribution type: %s

What it means

SyntheticOptions' distribution deserializer builds the random data distribution from a type name (e.g., UNIFORM, ZIPF, EXP, DEV_DELAYS) used by Beam's synthetic sources. If the configured distribution type string doesn't match any known case, deserialize throws IllegalArgumentException naming the unknown type.

Solutions

  1. Check the exact type string in your options JSON against the supported values in SyntheticOptions (case-sensitive).
  2. Use a known type such as UNIFORM, ZIPF, or EXP as listed in the DelayType/Distribution enum in this Beam version.
  3. Refer to the Beam version's SyntheticOptions source/docs for the current enum set, since values change between releases.

Example fix

// before (options JSON)
{"numRecords": 1000, "distributionType": "GAUSSIAN"}
// after
{"numRecords": 1000, "distributionType": "UNIFORM"}
Defensive patterns

Strategy: validation

Validate before calling

// Java — check the distribution type string before deserializing options
Set<String> known = Set.of("UNIFORM", "ZIPF", "EXP");
if (!known.contains(type)) {
  throw new IllegalArgumentException("distributionType must be one of " + known);
}

Try / catch

try {
  SyntheticOptions options = SyntheticOptions.fromJsonString(json);
} catch (IllegalArgumentException e) {
  // unknown distribution type: fix the type field in the options JSON
}

Prevention

When it happens

Trigger: Passing synthetic source options JSON (e.g., to SyntheticBoundedSource or the load-test pipeline) with a 'distributionType'/'type' field whose value doesn't match any supported enum constant.

Common situations: Typos in test-pipeline JSON options (e.g., 'zip' instead of 'zipf'), copying options from an older Beam version whose enum set differed, or case sensitivity issues in type names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/io/synthetic/src/main/java/org/apache/beam/sdk/io/synthetic/SyntheticOptions.java:291

        case "zipf":
          {
            double param = node.get("param").asDouble();
            final double multiplier =
                node.has("multiplier") ? node.get("multiplier").asDouble() : 1.0;
            checkArgument(
                param > 1,
                "The parameter of the Zipf distribution should be > 1, but found %s.",
                param);
            checkArgument(
                multiplier >= 0,
                "The multiplier of the Zipf distribution should be >= 0, but found %s.",
                multiplier);
            final ZipfDistribution dist = new ZipfDistribution(100, param);
            return scaledSampler(fromIntegerDistribution(dist), multiplier);
          }
        default:
          {
            throw new IllegalArgumentException("Unknown distribution type: " + type);
          }
      }
    }
  }

  public void validate() {
    checkArgument(
        keySizeBytes > 0, "keySizeBytes should be a positive number, but found %s", keySizeBytes);
    checkArgument(
        valueSizeBytes >= 0,
        "valueSizeBytes should be a non-negative number, but found %s",
        valueSizeBytes);
    checkArgument(
        numHotKeys >= 0, "numHotKeys should be a non-negative number, but found %s", numHotKeys);
    checkArgument(
        hotKeyFraction >= 0,
        "hotKeyFraction should be a non-negative number, but found %s",
        hotKeyFraction);

View on GitHub (pinned to 12126d8942)