apache/beam · error · java.lang.RuntimeException

Failed to parse option for

Error message

Failed to parse option for %s

What it means

getOptions parses Beam-specific schema options stored in proto field options and translates their values into Beam option values. Any RuntimeException raised while parsing a field's option value is rethrown wrapped as "Failed to parse option for <field name>" with the original exception as the cause. It indicates a schema option value in the proto descriptor could not be converted to the expected Beam type.

Solutions

1. Inspect the wrapped cause exception to find which field option value failed and fix the option's value type in the .proto (e.g. supply the string/bool/int the declared Beam option type expects).
2. Remove the offending schema option annotation from the field if it isn't needed.
3. Regenerate/normalize the proto annotations with the same Beam version used at runtime to avoid encoding mismatches.

Example fix

// before
FieldOptions opts = ...; // beam:option string_type option carrying an int value -> wrapped parse failure
// after
// in .proto: (beam_schema_option).beam_string_type = "expected-string-value";
// ensure value kind matches declared option type

// Java: before translating, verify each field's Beam schema option value matches its declared option type
for (Descriptors.FieldDescriptor f : msg.getDescriptorForType().getFields()) {
  // optionType vs optionValue kind must agree (STRING->string, BOOL->boolean, ...)
}

try { Schema s = ProtoSchemaTranslator.getSchema(descriptor); } catch (RuntimeException e) { if (e.getMessage().startsWith("Failed to parse option for ")) { /* inspect e.getCause() for the failing field option and fix its value type */ } else throw e; }

When it happens

Trigger: Reading schema options (getSchemaOptions/getFieldOptions) from a proto descriptor whose option value type doesn't match what the parser expects (e.g. an option declared for one Beam type — STRING, BOOL, etc. — carrying a value of an incompatible kind), triggering the IllegalStateException or a value-parsing failure.

Common situations: Hand-edited or code-generated protos with Beam schema annotations whose option values mismatch the declared Beam option type; protos annotated by another tool/version with a different option encoding.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

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

Related errors

• Aliased enumerations not currently supported.
• Any not yet supported
• Cannot create creator for
• cannot encode a null
• Cannot infer schema with a circular reference. Proto Field

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

Appendix: source

Thrown at sdks/java/extensions/protobuf/src/main/java/org/apache/beam/sdk/extensions/protobuf/ProtoSchemaTranslator.java:418

          case STRING:
          case BOOLEAN:
          case LOGICAL_TYPE:
          case ROW:
          case ARRAY:
          case ITERABLE:
            @SuppressWarnings("unchecked")
            ProtoBeamConverter.ProtoToBeamConverter<Object, Object> protoToBeamConverter =
                ProtoBeamConverter.createProtoToBeamConverter(fieldType);
            Object value = protoToBeamConverter.convert(entry.getValue());
            optionsBuilder.setOption(prefix + fieldDescriptor.getFullName(), fieldType, value);
            break;
          case MAP:
          case DATETIME:
          default:
            throw new IllegalStateException("These datatypes are not possible in extentions.");
        }
      } catch (RuntimeException e) {
        throw new RuntimeException(
            Strings.lenientFormat("Failed to parse option for %s", fieldDescriptor.getName()), e);
      }
    }
    return optionsBuilder;
  }
}

View on GitHub (pinned to 12126d8942)