apache/beam · error · RuntimeException

Cannot deserialize from a JSON string: .

Error message

Cannot deserialize %s from a JSON string: %s.

What it means

fromJsonString() deserializes a JSON string into a BigQuery model class with BigQueryIO's JSON_FACTORY. On IOException the library wraps the failure in a RuntimeException naming the target class and the offending JSON. Typically the JSON is malformed, truncated, or doesn't match the target class's schema.

Solutions

1. Print/inspect the JSON string in the message and validate it parses as the expected class.
2. Regenerate the JSON with BigQueryHelpers.toJsonString from a live object instead of reusing stale persisted data.
3. Ensure the Beam and google-api-services-bigquery versions match between writer and reader of the JSON.

Example fix

// before
JobConfiguration cfg = BigQueryHelpers.fromJsonString(staleJson, JobConfiguration.class);

// after
JobConfiguration cfg = BigQueryHelpers.fromJsonString(
    BigQueryHelpers.toJsonString(freshJobConfiguration), JobConfiguration.class);

if (json == null || json.isBlank()) {
  throw new IllegalArgumentException("cannot deserialize blank JSON into " + clazz);
}

try {
  T value = BigQueryHelpers.fromJsonString(json, clazz);
} catch (RuntimeException e) {
  // log json, regenerate from a live object via toJsonString
}

When it happens

Trigger: BigQueryHelpers.fromJsonString(json, clazz) called with null/invalid/corrupted JSON, or JSON produced by a different schema/version (e.g. hand-edited state stored in worker snapshots).

Common situations: Deserializing job state persisted to disk or stored in a field (e.g. LoadJobConfiguration in resizable shuffle state) after a Beam or BigQuery client library upgrade changed the model schema; corrupted encoded strings.

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.

Related errors

• Cannot serialize to 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/a422a6fea137b02e. 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:648

      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(
          String.format("Cannot deserialize %s from a JSON string: %s.", clazz, json), e);
    }
  }

  /**
   * Returns a randomUUID string.
   *
   * <p>{@code '-'} is removed because BigQuery doesn't allow it in dataset id.
   */
  static String randomUUIDString() {
    return UUID.randomUUID().toString().replaceAll("-", "");
  }

  static void verifyTableNotExistOrEmpty(DatasetService datasetService, TableReference tableRef) {
    try {
      if (datasetService.getTable(
              tableRef, Collections.emptyList(), DatasetService.TableMetadataView.BASIC)
          != null) {

View on GitHub (pinned to 12126d8942)