What causes "Cannot convert String `%s` to Enum value of type `%s`." in apple/pkl?

Correct the string in the Pkl config to exactly match an enum constant name of the target type (the message names the type).

apple/pkl · error · ConversionException

Cannot convert String `%s` to Enum value of type `%s`.

Error message

Cannot convert String `%s` to Enum value of type `%s`.

What it means

PStringToEnum converts a Pkl String to a Java enum constant by (case-sensitive) name lookup, with a fallback normalization via CodeGeneratorUtils.toEnumConstantName. This error is thrown when neither the raw string nor its normalized form matches any constant of the target enum type.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/PStringToEnum.java:79

        for (Enum<?> value : values) {
          enumValuesByName.put(value.name(), value);
        }
      }
    }

    @Override
    public Enum<?> convert(String value, ValueMapper valueMapper) {
      var enumValue = enumValuesByName.get(value);
      if (enumValue == null) {
        enumValue = enumValuesByName.get(CodeGeneratorUtils.toEnumConstantName(value));
        if (enumValue != null) {
          enumValuesByName.put(value, enumValue);
        }
      }
      if (enumValue != null) {
        return enumValue;
      }
      throw new ConversionException(
          String.format(
              "Cannot convert String `%s` to Enum value of type `%s`.",
              value, enumType.getTypeName()));
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

Correct the string in the Pkl config to exactly match an enum constant name of the target type (the message names the type).
Regenerate the Java enum with pkl-codegen-java if new values were added to the Pkl schema.
Match the naming convention expected by the converter (PascalCase Pkl value like "KiB" normalizes to KIB); rename the config value accordingly.
Register a custom Converter if you need lenient/alias mapping between strings and enum constants.

Example fix

// before
unit = "kiloBYTES"

// after: matches enum constant KIB via normalization
unit = "KiB"  // or exactly "KIB"

Defensive patterns

Strategy: validation

Validate before calling

// check the string maps to an enum constant before converting
boolean isValidEnumValue(String s, Class<? extends Enum<?>> type) {
  for (Enum<?> c : type.getEnumConstants()) {
    if (c.name().equals(s)) return true;
    String norm = CodeGeneratorUtils.toEnumConstantName(s);
    if (norm != null && c.name().equals(norm)) return true;
  }
  return false;
}

Type guard

static boolean isEnumConstant(String s, Class<? extends Enum<?>> type) {
  return java.util.Arrays.stream(type.getEnumConstants())
      .anyMatch(c -> c.name().equals(s));
}

Try / catch

try {
  return enumConverter.convert(configValue, valueMapper);
} catch (ConversionException e) {
  if (e.getMessage().startsWith("Cannot convert String")) {
    throw new ConfigLoadException(
        "Value '" + configValue + "' is not a valid " + enumType.getSimpleName(), e);
  }
  throw e;
}

Prevention

Use a Pkl enum type in the schema instead of a bare String so invalid values fail at evaluation time
Regenerate Java enums from the Pkl schema whenever enum values change
Match the codegen naming convention (Pkl "KiB" -> constant KIB)
List allowed values in config error output or docs to reduce typos

When it happens

Trigger: Converter.convert receiving a String whose value is not an existing enum constant name of enumType — e.g. Pkl config contains "KiB" but the Java enum declares KIB, a typo like "prodction", or a value added to the Pkl schema but not yet to the Java enum (or vice versa).

Common situations: Case mismatch between config value and enum constant; enum extended in Pkl but Java classes not regenerated; hand-written enums with names that don't follow the codegen naming convention; localized or free-text config values where a constrained enum is expected.

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/2919a2bf46bcfcb0. Report an issue: GitHub.