What causes "Invalid Duration unit symbol: " in apple/pkl?

Change the unit symbol to a valid Pkl duration unit: b, ms, s, min, h, or d

apple/pkl · error · PklException

Invalid Duration unit symbol:

Error message

Invalid Duration unit symbol:

What it means

Thrown by parsePObject when a Duration-typed JSON object carries a "unit" symbol that DurationUnit.parse cannot recognize. Valid Pkl duration units are b, ms, s, min, h, d. The library throws because it cannot map the serialized unit back to a DurationUnit enum value.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/DependencyMetadata.java:265

          }
          var unit = DataSizeUnit.parse(symbol);
          if (unit == null) {
            throw new PklException("Invalid DataSize unit symbol: " + symbol);
          }
          if (!(value instanceof Double num)) {
            throw new FormatException("double", value.getClass());
          }
          return new DataSize(num, unit);
        }
        case "Duration" -> {
          var symbol = jsObj.getString("unit");
          var value = jsObj.get("value");
          if (value == null) {
            throw new MissingFieldException(jsObj, "value");
          }
          var unit = DurationUnit.parse(symbol);
          if (unit == null) {
            throw new PklException("Invalid Duration unit symbol: " + symbol);
          }
          if (!(value instanceof Double num)) {
            throw new FormatException("double", value.getClass());
          }
          return new Duration(num, unit);
        }
        case "Pair" -> {
          var first = parsePObject(jsObj.get("first"));
          var second = parsePObject(jsObj.get("second"));
          return new Pair<>(first, second);
        }
      }
    }
    // should never be reached
    throw new PklException("Could not read annotation. Invalid object type: " + obj.getClass());
  }

  public static Checksums parseChecksums(Object obj) throws JsonParseException {

View on GitHub (pinned to f3efcbfc9b)

Solutions

Change the unit symbol to a valid Pkl duration unit: b, ms, s, min, h, or d
Regenerate the metadata file with the official Pkl serializer
Convert the value to a supported unit (e.g. "seconds" -> "s")

Example fix

// before
{"type": "Duration", "unit": "seconds", "value": 30.0}
// after
{"type": "Duration", "unit": "s", "value": 30.0}

Defensive patterns

Strategy: validation

Validate before calling

Set<String> VALID = Set.of("b","ms","s","min","h","d");
boolean hasValidDurationUnit(Object o) {
  return o instanceof Map<?,?> m && m.get("unit") instanceof String u && VALID.contains(u);
}

Try / catch

try {
  var d = DependencyMetadata.parsePObject(json);
} catch (PklException e) {
  if (e.getMessage().startsWith("Invalid Duration unit symbol")) {
    log.error("Unsupported duration unit; use b, ms, s, min, h, or d", e);
  }
}

Prevention

Only use Pkl duration unit symbols (b, ms, s, min, h, d) in metadata
Convert spelled-out units (seconds, minutes) to symbols before serializing
Regenerate metadata with the official Pkl serializer rather than custom code

When it happens

Trigger: Parsing metadata JSON like {"type":"Duration","unit":"seconds","value":5.0} — any unit symbol outside {b, ms, s, min, h, d}, including null or an empty string, triggers this.

Common situations: Metadata produced by a non-Pkl tool that spelled out unit names ("seconds", "msec") or used abbreviations like "us"/"ns" that Pkl does not support.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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