apache/beam · error · IllegalArgumentException

Unknown resource hint:

Error message

Unknown resource hint: 

What it means

When parsing resource hints, Beam maps known hint names (e.g. 'cpu_count') to URNs. If a hint's name is not a known one and doesn't start with the reserved prefix 'beam:resources:', Beam rejects it with IllegalArgumentException('Unknown resource hint: <hint>') to catch typos.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/resourcehints/ResourceHints.java:120

  /** Creates a {@link ResourceHints} instance with hints supplied in options. */
  public static ResourceHints fromOptions(PipelineOptions options) {
    ResourceHintsOptions resourceHintsOptions = options.as(ResourceHintsOptions.class);
    ResourceHints result = create();
    List<String> hints = resourceHintsOptions.getResourceHints();
    Splitter splitter = Splitter.on('=').limit(2);
    for (String hint : hints) {
      List<String> parts = splitter.splitToList(hint);
      if (parts.size() != 2) {
        throw new IllegalArgumentException("Unparsable resource hint: " + hint);
      }
      String nameOrUrn = parts.get(0);
      String stringValue = parts.get(1);
      String urn;
      if (hintNameToUrn.containsKey(nameOrUrn)) {
        urn = hintNameToUrn.get(nameOrUrn);
      } else if (!nameOrUrn.startsWith("beam:resources:")) {
        // Allow unknown hints to be passed, but validate a little bit to prevent typos.
        throw new IllegalArgumentException("Unknown resource hint: " + hint);
      } else {
        urn = nameOrUrn;
      }
      ResourceHint value =
          Preconditions.checkNotNull(parsers.getOrDefault(urn, StringHint::new)).apply(stringValue);
      result = result.withHint(urn, value);
    }
    return result;
  }

  /*package*/ static class BytesHint extends ResourceHint {
    private static Map<String, Long> suffixes =
        ImmutableMap.<String, Long>builder()
            .put("B", 1L)
            .put("KB", 1000L)
            .put("MB", 1000_000L)
            .put("GB", 1000_000_000L)
            .put("TB", 1000_000_000_000L)

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the hint name spelling to a registered hint (e.g. cpu_count, min_ram_mb)
2. Use the full URN form for custom hints: beam:resources:my_custom_hint=value
3. Check the Beam/runner version supports the hint name you are using
4. List available hints via ResourceHints known parsers/URNs to verify valid names

Example fix

// before
--resourceHints=cpu_cout=2

// after
--resourceHints=cpu_count=2

Set<String> known = Set.of("cpu_count", "min_ram_mb");
for (String hint : hints) {
  String name = hint.split("=", 2)[0];
  if (!known.contains(name) && !name.startsWith("beam:resources:")) {
    throw new IllegalArgumentException("Unknown resource hint name: " + name);
  }
}

try {
  ResourceHints.fromOptions(options);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown resource hint:")) {
    // correct the name or switch to a beam:resources: URN
  }
}

When it happens

Trigger: Supplying a hint name that isn't registered (e.g. --resourceHints=cpu_cout=2 typo) and that isn't a beam:resources: URN; the check nameOrUrn.startsWith("beam:resources:") fails, so it throws.

Common situations: Typos in hint names; using hints from a different Beam version or runner where the name isn't registered; custom hints not prefixed with the required 'beam:resources:' URN scheme.

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

• Unparsable resource hint:
• Unable to parse '" + s + "' as a byte value.
• Timing number 0b" + timingNumber.toString(2) + " has more th
• No proto encoding for PaneInfoCoder, always part of Windowed
• Runner does not support draining.

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