apache/beam · error · RuntimeException

illegal table properties: ${json}

Error message

illegal table properties: ${json}

What it means

TableUtils.parseProperties parses a JSON string into a Jackson ObjectNode representing table properties. If the string is not valid JSON (or not an object tree Jackson can read), the JsonProcessingException is rethrown as a RuntimeException with the offending input embedded.

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/TableUtils.java:62

  private TableUtils() {
    // nothing here
  }

  @VisibleForTesting
  public static ObjectMapper getObjectMapper() {
    return objectMapper;
  }

  public static ObjectNode emptyProperties() {
    return objectMapper.createObjectNode();
  }

  public static ObjectNode parseProperties(String json) {
    try {
      return (ObjectNode) objectMapper.readTree(json);
    } catch (JsonProcessingException e) {
      throw new RuntimeException("illegal table properties: " + json);
    }
  }

  public static ObjectNode parseProperties(Map<String, String> map) {
    return objectMapper.valueToTree(map);
  }

  public static Map<String, Object> convertNode2Map(JsonNode jsonNode) {
    return objectMapper.convertValue(jsonNode, new TypeReference<Map<String, Object>>() {});
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

  1. Validate the JSON string with a linter before passing it (e.g. JSON must use double quotes: {"a":"b"})
  2. Use parseProperties(Map<String,String>) overload to build properties from a map and skip JSON parsing entirely
  3. Catch the RuntimeException and surface the offending string to the user for correction

Example fix

// before
TableUtils.parseProperties("{'a':1}");
// after
TableUtils.parseProperties("{\"a\":1}");
Defensive patterns

Strategy: try-catch

Validate before calling

objectMapper.readTree(json); // pre-validate in a probe call

Try / catch

try { TableUtils.parseProperties(json); } catch (RuntimeException e) { throw new IllegalArgumentException("Fix TBLPROPERTIES JSON: " + json, e); }

Prevention

When it happens

Trigger: Calling parseProperties(String) with malformed JSON — trailing commas, single quotes, unquoted keys, or non-JSON text — typically from a table DDL TBLPROPERTIES clause.

Common situations: Hand-written TBLPROPERTIES using map-like syntax {'a':'b'} instead of JSON, copy/paste artifacts, encoding issues.

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.

Related errors

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