{"record":{"id":"a422a6fea137b02e","repo":"apache/beam","slug":"cannot-deserialize-s-from-a-json-string-s","errorCode":null,"errorMessage":"Cannot deserialize %s from a JSON string: %s.","messagePattern":"Cannot deserialize (.+?) from a JSON string: (.+?)\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryHelpers.java","lineNumber":648,"sourceCode":"      throw new RuntimeException(\n          String.format(\"Cannot serialize %s to a JSON string.\", item.getClass().getSimpleName()),\n          e);\n    }\n  }\n\n  public static <T> @PolyNull T fromJsonString(@PolyNull String json, Class<T> clazz) {\n    if (json == null) {\n      return null;\n    }\n    try {\n      // If T is Void then this ends up null, otherwise it is not; kind of a tough invariant\n      @SuppressWarnings({\n        \"nullness\" // TODO(https://github.com/apache/beam/issues/20497)\n      })\n      @NonNull T result = BigQueryIO.JSON_FACTORY.fromString(json, clazz);\n      return result;\n    } catch (IOException e) {\n      throw new RuntimeException(\n          String.format(\"Cannot deserialize %s from a JSON string: %s.\", clazz, json), e);\n    }\n  }\n\n  /**\n   * Returns a randomUUID string.\n   *\n   * <p>{@code '-'} is removed because BigQuery doesn't allow it in dataset id.\n   */\n  static String randomUUIDString() {\n    return UUID.randomUUID().toString().replaceAll(\"-\", \"\");\n  }\n\n  static void verifyTableNotExistOrEmpty(DatasetService datasetService, TableReference tableRef) {\n    try {\n      if (datasetService.getTable(\n              tableRef, Collections.emptyList(), DatasetService.TableMetadataView.BASIC)\n          != null) {","sourceCodeStart":630,"sourceCodeEnd":666,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryHelpers.java#L630-L666","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Print/inspect the JSON string in the message and validate it parses as the expected class.","Regenerate the JSON with BigQueryHelpers.toJsonString from a live object instead of reusing stale persisted data.","Ensure the Beam and google-api-services-bigquery versions match between writer and reader of the JSON."],"exampleFix":"// before\nJobConfiguration cfg = BigQueryHelpers.fromJsonString(staleJson, JobConfiguration.class);\n\n// after\nJobConfiguration cfg = BigQueryHelpers.fromJsonString(\n    BigQueryHelpers.toJsonString(freshJobConfiguration), JobConfiguration.class);","handlingStrategy":"validation","validationCode":"if (json == null || json.isBlank()) {\n  throw new IllegalArgumentException(\"cannot deserialize blank JSON into \" + clazz);\n}","typeGuard":null,"tryCatchPattern":"try {\n  T value = BigQueryHelpers.fromJsonString(json, clazz);\n} catch (RuntimeException e) {\n  // log json, regenerate from a live object via toJsonString\n}","preventionTips":["Round-trip through toJsonString/fromJsonString with the same library versions.","Validate persisted JSON against the current model class before use.","Pin Beam/BigQuery client versions so serialized state schemas stay compatible."],"tags":["java","bigquery","json-deserialization","jackson"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}