apache/beam · error · RuntimeException

Unable to parse representation

Error message

Unable to parse representation

What it means

When reading PipelineOptions back from a JSON representation (e.g., after template deserialization), ProxyInvocationHandler.getValueFromJson delegates to PipelineOptionsFactory.deserializeNode. If that throws an IOException (malformed or incompatible JSON for the option's type), it is rethrown as a RuntimeException with message 'Unable to parse representation'.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/ProxyInvocationHandler.java:611

  }

  /**
   * Uses a Jackson {@link ObjectMapper} to attempt type conversion.
   *
   * @param method The method whose return type you would like to return.
   * @param propertyName The name of the property that is being returned.
   * @return An object matching the return type of the method passed in.
   */
  private Object getValueFromJson(String propertyName, Method method) {
    JsonNode jsonNode = jsonOptions.get(propertyName);
    return getValueFromJson(jsonNode, method);
  }

  private static Object getValueFromJson(JsonNode node, Method method) {
    try {
      return PipelineOptionsFactory.deserializeNode(node, method);
    } catch (IOException e) {
      throw new RuntimeException("Unable to parse representation", e);
    }
  }

  /**
   * Returns a default value for the method based upon {@code @Default} metadata on the getter to
   * return values. If there is no {@code @Default} annotation on the getter, then a <a href=
   * "https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html">default</a> as per
   * the Java Language Specification for the expected return type is returned.
   *
   * @param proxy The proxy object for which we are attempting to get the default.
   * @param method The getter method that was invoked.
   * @return The default value from an {@link Default} annotation if present, otherwise a default
   *     value as per the Java Language Specification.
   */
  @SuppressWarnings({"unchecked", "rawtypes"})
  private Object getDefault(PipelineOptions proxy, Method method) {
    if (method.getReturnType().equals(RuntimeValueProvider.class)) {
      throw new RuntimeException(

View on GitHub (pinned to 12126d8942)

Solutions

1. Inspect the wrapped cause (getCause()) to find the exact property and IOException.
2. Regenerate the template/JSON from the same Beam version instead of hand-editing it.
3. Ensure the getter type has a valid Jackson deserializer and matches the JSON shape in the node.
4. Remove or fix the offending property value in the JSON input.

// Validate JSON node before feeding options deserialization
if (node == null || node.isMissingNode()) {
  throw new IllegalArgumentException("Missing options JSON node");
}

try {
  MyOptions opts = PipelineOptionsFactory.fromArgs(...).create();
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("Unable to parse representation")) {
    LOG.error("Bad options JSON", e.getCause()); // inspect cause for property/type
  }
}

When it happens

Trigger: Calling PipelineOptionsFactory/serialization APIs that populate options from a JSON tree where a property's JSON node cannot be deserialized to the getter's declared type — e.g., corrupted or hand-edited template JSON, or a mismatched type for a @Default Jackson-deserializable option.

Common situations: Loading a saved pipeline template whose JSON was edited or produced by a different Beam version; a custom JacksonDeserializable option whose serialized form no longer matches its class; passing non-JSON-serializable values through jsonFactory-based output.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Field '{name}' is not present in the JSON object.
• Field '{name}' has a null value in the JSON object.
• Found incorrectly annotated property methods, if a method is
• Unable to parse JSON value
• Error deserializing via Coder

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