apache/beam · error · RuntimeException

Unknown mode %s

Error message

Unknown mode %s

What it means

protoModeToJsonMode translates a protobuf TableFieldSchema.Mode (NULLABLE/REQUIRED/REPEATED) to the legacy JSON API mode string via MODE_MAP_PROTO_JSON. If the proto mode has no mapping (e.g. an unknown/added enum value from a newer API version), it throws RuntimeException("Unknown mode ...").

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/TableRowToStorageApiProto.java:579

        Optional.ofNullable(mode)
            .map(Mode::valueOf)
            .map(MODE_MAP_JSON_PROTO::get)
            .orElse(TableFieldSchema.Mode.NULLABLE);
    if (defaultValueExpression == null) {
      return resultMode;
    } else {
      // If there is a default value expression, treat this field as if it were nullable or
      // repeated.
      return resultMode.equals(TableFieldSchema.Mode.REPEATED)
          ? resultMode
          : TableFieldSchema.Mode.NULLABLE;
    }
  }

  public static String protoModeToJsonMode(TableFieldSchema.Mode protoMode) {
    String jsonMode = MODE_MAP_PROTO_JSON.get(protoMode);
    if (jsonMode == null) {
      throw new RuntimeException("Unknown mode " + protoMode);
    }
    return jsonMode;
  }

  public static String protoTypeToJsonType(TableFieldSchema.Type protoType) {
    String type = TYPE_MAP_PROTO_JSON.get(protoType);
    if (type == null) {
      throw new RuntimeException("Unknown type " + protoType);
    }
    return type;
  }

  public static TableFieldSchema.Type typeToProtoType(String type) {
    TableFieldSchema.Type protoType = TYPE_MAP_JSON_PROTO.get(type);
    if (protoType == null) {
      throw new RuntimeException("Unknown type " + type);
    }
    return protoType;

View on GitHub (pinned to 12126d8942)

Solutions

  1. Upgrade google-cloud-bigquery / Beam to a version whose MODE_MAP_PROTO_JSON covers the schema's mode values.
  2. Inspect the schema (bq show --schema) and normalize modes to NULLABLE/REQUIRED/REPEATED before feeding the pipeline.
  3. If hand-building schemas, use TableFieldSchema.Mode values known to Beam.

Example fix

// before
TableFieldSchema.Mode mode = TableFieldSchema.Mode.UNRECOGNIZED_VALUE; // from newer API
// after
// upgrade dependencies or map manually:
String jsonMode = protoMode == null ? "NULLABLE" : protoMode.name();
Defensive patterns

Strategy: try-catch

Validate before calling

if (TableFieldSchema.Mode.UNRECOGNIZED_VALUE.equals(protoMode)) {
  throw new IllegalArgumentException("Mode not supported by this Beam version: " + protoMode);
}

Try / catch

try {
  String jsonMode = TableRowToStorageApiProto.protoModeToJsonMode(protoMode);
} catch (RuntimeException e) {
  LOG.error("Unmapped proto mode {}; upgrade Beam/gcloud libs", protoMode, e);
  throw e;
}

Prevention

When it happens

Trigger: Calling protoModeToJsonMode with a TableFieldSchema.Mode value absent from MODE_MAP_PROTO_JSON, e.g. a mode introduced by a newer BigQuery Storage API than the Beam version's map covers.

Common situations: Running an older Beam version against schemas produced by a newer BigQuery API/client that emits an unrecognized mode; hand-constructed proto schemas with null or exotic modes.

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/730632f35c87002e. Report an issue: GitHub.