apache/beam · error · IllegalArgumentException

can not be deserialized from Json

Error message

 can not be deserialized from Json

What it means

AwsSerializableUtils.deserialize wraps any IOException thrown by Jackson's ObjectMapper.readValue in an IllegalArgumentException, reporting that the target class 'can not be deserialized from Json'. It is thrown whenever the JSON payload cannot be parsed or does not match the target type's schema. Used internally by AWS2 IO connectors to serialize/deserialize options such as Sqs/Sns/AwsModels.

Solutions

1. Verify the serialized string is valid JSON and matches the target class schema
2. Regenerate the serialized payload with AwsSerializableUtils.serialize using the same library version
3. Check for version skew between the writer and reader of the payload (e.g. checkpoint data from an older pipeline)
4. Enable Jackson FAIL_ON_UNKNOWN_PROPERTIES:false or update the target class if new fields were added

Example fix

// before
MyOptions opts = AwsSerializableUtils.deserialize(corruptedJson, MyOptions.class);
// after
MyOptions opts;
try {
  opts = AwsSerializableUtils.deserialize(json, MyOptions.class);
} catch (IllegalArgumentException e) {
  opts = AwsSerializableUtils.serializeDeserializeDefault(); // regenerate from defaults
}

if (json == null || json.isBlank() || !json.trim().startsWith("{")) throw new IllegalArgumentException("Not valid JSON: " + json);

static boolean isValidJson(String s) { try { MAPPER.readTree(s); return true; } catch (IOException e) { return false; } }

try { T v = AwsSerializableUtils.deserialize(json, MyOptions.class); } catch (IllegalArgumentException e) { LOG.error("deserialization failed", e); }

When it happens

Trigger: Calling AwsSerializableUtils.deserialize with a corrupted, truncated, or empty JSON string; passing JSON whose structure does not match the target class; deserializing a payload written by an incompatible older/newer schema version (e.g. via testSerializerRejectsUnknownVersionsAndUnexpectedPayloads).

Common situations: State persisted in checkpoints or job state files becomes stale after upgrading the Beam AWS2 SDK or the AWS SDK v2; hand-edited serialized options; passing a non-JSON plain string to deserialize.

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

• Failed to parse a from JSON value
• Field ' ' has a null value in the JSON object.
• Field ' ' is not present in the JSON object.
• Unable to parse representation
• Azure credentials provider could not be read.

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

Appendix: source

Thrown at sdks/java/io/amazon-web-services2/src/main/java/org/apache/beam/sdk/io/aws2/options/AwsSerializableUtils.java:57

  public static AwsCredentialsProvider deserializeAwsCredentialsProvider(
      String serializedCredentialsProvider) {
    return deserialize(serializedCredentialsProvider, AwsCredentialsProvider.class);
  }

  static String serialize(Object object) {
    try {
      return MAPPER.writeValueAsString(object);
    } catch (JsonProcessingException e) {
      throw new IllegalArgumentException(
          object.getClass().getSimpleName() + " can not be serialized to Json", e);
    }
  }

  static <T> T deserialize(String serializedObject, Class<T> clazz) {
    try {
      return MAPPER.readValue(serializedObject, clazz);
    } catch (IOException e) {
      throw new IllegalArgumentException(
          clazz.getSimpleName() + " can not be deserialized from Json", e);
    }
  }
}

View on GitHub (pinned to 12126d8942)