apache/beam · error · IllegalArgumentException

Unable to parse JSON value

Error message

Unable to parse JSON value 

What it means

A JSON string value supplied for an option could not be parsed into the property's type by tryParseObject; the IOException is wrapped in an IllegalArgumentException prefixed with 'Unable to parse JSON value '. In non-strict mode the error is swallowed, so this surfaces only with strict parsing enabled.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/PipelineOptionsFactory.java:1964

          if (values.contains("")) {
            checkEmptyStringAllowed(returnType, type, method.getGenericReturnType().toString());
          }
          convertedOptions.put(entry.getKey(), MAPPER.convertValue(values, type));
        } else if (isSimpleType(returnType, type)) {
          String value = Iterables.getOnlyElement(entry.getValue());
          if (value.isEmpty()) {
            checkEmptyStringAllowed(returnType, type, method.getGenericReturnType().toString());
          }
          convertedOptions.put(entry.getKey(), MAPPER.convertValue(value, type));
        } else {
          String value = Iterables.getOnlyElement(entry.getValue());
          if (value.isEmpty()) {
            checkEmptyStringAllowed(returnType, type, method.getGenericReturnType().toString());
          }
          try {
            convertedOptions.put(entry.getKey(), tryParseObject(value, method));
          } catch (IOException e) {
            throw new IllegalArgumentException("Unable to parse JSON value " + value, e);
          }
        }
      } catch (IllegalArgumentException e) {
        if (strictParsing) {
          throw e;
        } else {
          LOG.warn(
              "Strict parsing is disabled, ignoring option '{}' with value '{}'",
              entry.getKey(),
              entry.getValue(),
              e);
        }
      }
    }
    return convertedOptions;
  }

  /**

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the JSON syntax of the value (quote keys, balance braces/brackets)
2. Escape quotes properly for your shell (single-quote the whole --arg=value token)
3. Set the option programmatically on the options interface instead of via JSON string

Example fix

// before
--inputFiles=[file1.txt, file2.txt]
// after
--inputFiles='["file1.txt","file2.txt"]'

new ObjectMapper().readTree(rawValue); // throws JsonProcessingException early if malformed

try { fromArgs(args).as(Opts.class); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unable to parse JSON")) { /* fix value format */ } }

When it happens

Trigger: Providing malformed JSON for a structured/list/complex option (e.g., --opt={a,b} instead of {"a":"b"}) while strictParsing is true, when converting args or a JSON options map.

Common situations: Unquoted or unescaped JSON on the command line; nested quotes mangled by shell escaping; passing a plain string where a JSON array/object is expected.

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

• Found incorrectly annotated property methods, if a method is
• Class %s missing a property named '%s'.
• Class %s missing a property named '%s'. Did you mean '%s'?
• Class %s missing a property named '%s'. Did you mean one of
• Empty argument value is only allowed for String, String Arra

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