apache/beam · error · RuntimeException

Failed to parse a %s from JSON value: %s

Error message

Failed to parse a %s from JSON value: %s

What it means

ParseJsons<OutputT> parses JSON strings into OutputT instances using a Jackson ObjectMapper. A readValue failure (malformed JSON, shape mismatch, missing module) throws IOException, which is rethrown as a RuntimeException identifying the target class and the offending JSON string.

Source

Thrown at sdks/java/extensions/jackson/src/main/java/org/apache/beam/sdk/extensions/jackson/ParseJsons.java:157

        exceptionHandler, exceptionHandler.getOutputTypeDescriptor());
  }

  private OutputT readValue(String input) throws IOException {
    ObjectMapper mapper = Optional.ofNullable(customMapper).orElse(DEFAULT_MAPPER);
    return mapper.readValue(input, outputClass);
  }

  @Override
  public PCollection<OutputT> expand(PCollection<String> input) {
    return input.apply(
        MapElements.via(
            new SimpleFunction<String, OutputT>() {
              @Override
              public OutputT apply(String input) {
                try {
                  return readValue(input);
                } catch (IOException e) {
                  throw new RuntimeException(
                      "Failed to parse a " + outputClass.getName() + " from JSON value: " + input,
                      e);
                }
              }
            }));
  }

  /** A {@code PTransform} that adds exception handling to {@link ParseJsons}. */
  public class ParseJsonsWithFailures<FailureT>
      extends PTransform<PCollection<String>, WithFailures.Result<PCollection<OutputT>, FailureT>> {

    private @Nullable InferableFunction<WithFailures.ExceptionElement<String>, FailureT>
        exceptionHandler;

    private final transient @Nullable TypeDescriptor<FailureT> failureType;

    ParseJsonsWithFailures(
        InferableFunction<WithFailures.ExceptionElement<String>, FailureT> exceptionHandler,

View on GitHub (pinned to 12126d8942)

Solutions

1. Validate/repair upstream JSON (parse each line with try/catch before the transform, or filter invalid records)
2. Ensure the target class matches the JSON schema (annotations like @JsonIgnoreProperties(ignoreUnknown=true))
3. Provide a configured ObjectMapper via withObjectMapper, registering required modules

Example fix

// before
ParseJsons.toClass(Event.class) // fails on java.time fields
// after
ObjectMapper mapper = new ObjectMapper().registerModule(new JavaTimeModule())
    .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
ParseJsons.<Event>withObjectMapper(mapper).apply(jsonLines);

try { mapper.readValue(sampleJson, Target.class); } catch (IOException e) { /* reject or repair input before the pipeline */ }

try { parsed = ParseJsons.toClass(Event.class).apply(jsonLines); } catch (RuntimeException e) { if (e.getMessage().startsWith("Failed to parse a")) { /* validate JSON or align schema, re-run */ } else throw e; }

When it happens

Trigger: Applying ParseJsons.toClass(TypeT) to input strings that are not valid JSON or do not match the target schema (wrong field types, unknown structure), or missing modules for types like Instant.

Common situations: Malformed lines in a text/JSON source, wrong Dataflow/POJO class after schema evolution, missing jackson-datatype-jsr310 module for java.time types.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unable to parse representation
• Field '{name}' is not present in the JSON object.
• Field '{name}' has a null value in the JSON object.
• Failed to read PipelineOptions from Protocol
• Failed to serialize %s value: %s

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