apache/beam · error · RuntimeException

Cannot serialize to a JSON string.

Error message

Cannot serialize %s to a JSON string.

What it means

toJsonString() serializes BigQuery API model objects to JSON via BigQueryIO's Jackson JSON_FACTORY. If Jackson throws IOException during serialization, the library wraps it in a RuntimeException stating the class couldn't be serialized. This almost always indicates the object contains content Jackson cannot write (rare with the API model classes).

Solutions

1. Check the wrapped IOException cause for the Jackson serialization detail.
2. Use the standard com.google.api.services.bigquery.model classes rather than custom subclasses.
3. If serialization of a custom type is needed, register a module/serializer on your own ObjectMapper instead of relying on BigQueryIO.JSON_FACTORY.

try {
  String json = BigQueryHelpers.toJsonString(item);
} catch (RuntimeException e) {
  // inspect cause IOException for the Jackson serialization failure
}

When it happens

Trigger: BigQueryHelpers.toJsonString(item) called with a TableReference/Job/JobConfiguration whose Jackson serialization fails (non-standard getters, self-referencing fields, custom subclasses not recognized by the JSON factory).

Common situations: Passing a custom subclass of a BigQuery model class that introduces properties the Jackson factory can't handle, or a corrupted object graph; uncommon with plain API model objects.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• Cannot deserialize from a JSON string: .
• A function must be provided to convert the input type into…
• Azure credential provider type
• Azure credentials provider could not be read.
• Azure credentials provider type name key

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

Appendix: source

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

    }
    JobStatus status = job.getStatus();
    if (status.getErrorResult() != null) {
      return Status.FAILED;
    } else if (status.getErrors() != null && !status.getErrors().isEmpty()) {
      return Status.FAILED;
    } else {
      return Status.SUCCEEDED;
    }
  }

  public static @PolyNull String toJsonString(@PolyNull Object item) {
    if (item == null) {
      return null;
    }
    try {
      return BigQueryIO.JSON_FACTORY.toString(item);
    } catch (IOException e) {
      throw new RuntimeException(
          String.format("Cannot serialize %s to a JSON string.", item.getClass().getSimpleName()),
          e);
    }
  }

  public static <T> @PolyNull T fromJsonString(@PolyNull String json, Class<T> clazz) {
    if (json == null) {
      return null;
    }
    try {
      // If T is Void then this ends up null, otherwise it is not; kind of a tough invariant
      @SuppressWarnings({
        "nullness" // TODO(https://github.com/apache/beam/issues/20497)
      })
      @NonNull T result = BigQueryIO.JSON_FACTORY.fromString(json, clazz);
      return result;
    } catch (IOException e) {
      throw new RuntimeException(

View on GitHub (pinned to 12126d8942)