apple/pkl · error · ConversionException

Cannot convert pkl.base#String `%s` to java.lang.Character b

Error message

Cannot convert pkl.base#String `%s` to java.lang.Character because it is not of length 1.

What it means

Conversions.pStringToCharacter maps a Pkl String to a Java Character and throws ConversionException unless the string is exactly one character long. Since there is no Pkl char type, single-character strings are the convention, and this check prevents silently taking charAt(0) of a longer string.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java:124

  public static final Conversion<Double, Float> pFloatToFloat =
      Conversion.of(PClassInfo.Float, float.class, (value, mapper) -> value.floatValue());

  /** Conversion from {@code pkl.base#Float} to {@link BigDecimal}. */
  public static final Conversion<Double, BigDecimal> pFloatToBigDecimal =
      Conversion.of(
          PClassInfo.Float, BigDecimal.class, (value, mapper) -> BigDecimal.valueOf(value));

  /**
   * Conversion from {@code pkl.base#String} to {@link Character}. Throws {@link
   * ConversionException} if the String value is not of length one.
   */
  public static final Conversion<String, Character> pStringToCharacter =
      Conversion.of(
          PClassInfo.String,
          Character.class,
          (value, mapper) -> {
            if (value.length() != 1) {
              throw new ConversionException(
                  String.format(
                      "Cannot convert pkl.base#String `%s` to java.lang.Character because it is not of length 1.",
                      value));
            }
            return value.charAt(0);
          });

  /**
   * Conversion from {@code pkl.base#String} to {@link URI}. Throws {@link ConversionException} if
   * the String value is not a syntactically valid URI.
   */
  public static final Conversion<String, URI> pStringToURI =
      Conversion.of(
          PClassInfo.String,
          URI.class,
          (value, mapper) -> {
            try {
              return new URI(value);

View on GitHub (pinned to f3efcbfc9b)

Solutions

Fix the .pkl value to be exactly one character, or correct the intended single-char constant.
Change the Java target type to String if multi-character values are legitimate, and update the mapping.
Validate the string length in Pkl itself: sep: String(length == 1) (or String(length(this) == 1) as applicable) so bad values fail at evaluation.
Trim/normalize the value before mapping if whitespace may be inflating the length.

Example fix

// before: in .pkl
separator: String = "::" // length 2 -> ConversionException
// after
separator: String(length == 1) = ":"

Defensive patterns

Strategy: validation

Validate before calling

// validate before mapping to Character
static char checkedToChar(String value) {
  if (value == null || value.length() != 1)
    throw new IllegalArgumentException("expected single character, got: '" + value + "'");
  return value.charAt(0);
}

Type guard

static boolean isSingleChar(String s) { return s != null && s.length() == 1; }

Try / catch

try {
  Character c = mapper.map(value, Character.class);
} catch (ConversionException e) {
  log.error("expected 1-char Pkl String: {}", e.getMessage());
  throw new ConfigValidationException("separator/mode must be a single character", e);
}

Prevention

Constrain in Pkl: prop: String(length == 1)
Use String in the Java schema when values may be longer
Trim values in .pkl to avoid accidental whitespace making length 2
Cover single-char config values with tests using both empty and multi-char inputs

When it happens

Trigger: Mapping a Pkl String property to a Java char/Character field where the .pkl value has length 0 or >= 2, e.g. a separator, mode flag, or currency symbol accidentally written as a multi-character or empty string.

Common situations: Writing "" instead of a real character in the .pkl config; a value like "--" or "ab" where a single delimiter was intended; locale/keyboard mistakes; generated Java schema declaring Character for what the Pkl data treats as free text.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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