apple/pkl · error · FormatException

FormatException(key, "boolean", ret.getClass())

Error message

FormatException(key, "boolean", ret.getClass())

What it means

JsObject.getBoolean(key) throws FormatException when the key exists but its value is not a JSON boolean (e.g. the string "true", the number 1, or an object). The exception records the expected type "boolean" and the actual value class.

Solutions

1. Fix the producer to emit real JSON booleans (true/false).
2. Read with a lenient mapper (e.g. map "true"/1 to Boolean yourself) via get(key, mapper).
3. Validate the payload against a schema before extraction.

Example fix

// before
boolean enabled = obj.getBoolean("enabled"); // value: "true"
// after
boolean enabled = obj.get("enabled", v ->
    v instanceof Boolean b ? b : Boolean.parseBoolean(((JsString) v).value()));

Object v = obj.getNullable("enabled", Function.identity());
if (!(v instanceof Boolean)) throw new IllegalArgumentException("'enabled' must be a JSON boolean, got: " + (v == null ? "null" : v.getClass()));

Object v = obj.getNullable("enabled", Function.identity());
boolean enabled = v instanceof Boolean b ? b : (v instanceof JsString s ? Boolean.parseBoolean(s.value()) : false);

try {
  boolean enabled = obj.getBoolean("enabled");
} catch (Json.FormatException e) {
  // value present but wrong type; coerce or fail with context
}

When it happens

Trigger: Calling getBoolean on a field holding a non-boolean JSON type, e.g. {"enabled": "true"} or {"enabled": 1}.

Common situations: Producers encoding booleans as strings/ints; YAML-derived or legacy JSON where 0/1 represent booleans; schema drift after API changes.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• object
• double
• FormatException(key, "array", ret.getClass())
• FormatException(key, "integer", ret.getClass())
• FormatException(key, "object", ret.getClass())

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/bbf211753ce7e82f. Report an issue: GitHub.

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/util/json/Json.java:257

        throw new MappingException(key, e);
      }
    }

    public <T> @Nullable T getNullable(String key, Mapper<T> mapper) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        return null;
      }
      return get(key, mapper);
    }

    public boolean getBoolean(String key) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        throw new MissingFieldException(this, key);
      }
      if (!(ret instanceof Boolean b)) {
        throw new FormatException(key, "boolean", ret.getClass());
      }
      return b;
    }

    public int getInt(String key) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        throw new MissingFieldException(this, key);
      }
      if (!(ret instanceof Integer i)) {
        throw new FormatException(key, "integer", ret.getClass());
      }
      return i;
    }

    public String getString(String key) throws JsonParseException {
      var ret = getStringOrNull(key);
      if (ret == null) {

View on GitHub (pinned to f3efcbfc9b)