apache/beam · error · IllegalArgumentException

Unparsable resource hint:

Error message

Unparsable resource hint: 

What it means

ResourceHints.fromOptions parses each hint string from the 'resourceHints' pipeline option expecting the form 'name=value' (or 'urn=value'). If a hint string contains no '=' separator (after splitting with limit 2, it doesn't produce exactly 2 parts), Beam throws IllegalArgumentException('Unparsable resource hint: <hint>').

Source

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

  private ResourceHints(ImmutableMap<String, ResourceHint> hints) {
    this.hints = hints;
  }

  /** Creates a {@link ResourceHints} instance with no hints. */
  public static ResourceHints create() {
    return EMPTY;
  }

  /** 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;
  }

View on GitHub (pinned to 12126d8942)

Solutions

1. Format each hint as 'name=value' or 'beam:resources:xxx=value', e.g. --resourceHints=cpu_count=2
2. Check the option value for stray characters or quoting that removed the '='
3. Split multiple hints correctly (the option accepts a list; don't join hints without separators Beam understands)
4. Log/print the offending hint from the message and fix that exact entry

Example fix

// before
--resourceHints=accelerator:gpu

// after
--resourceHints=accelerator=gpu

// Validate each hint before handing to Beam
for (String hint : hints) {
  if (!hint.contains("=") || hint.startsWith("=") || hint.endsWith("=")) {
    throw new IllegalArgumentException("Hint must be name=value: " + hint);
  }
}

try {
  ResourceHints.fromOptions(options);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unparsable resource hint:")) {
    logger.error("Fix hint format to name=value: {}", e.getMessage());
  }
}

When it happens

Trigger: Passing a pipeline option like --resourceHints=cpu_amount or --resourceHints=accelerator:gpu (missing '=') such that Splitter.on('=').limit(2).splitToList(hint) returns a list whose size != 2.

Common situations: CLI misconfiguration where users write 'name:value' instead of 'name=value'; empty strings in the hints list; YAML/JSON quoting stripping the '='; copy-paste of hint names without values.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

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