apple/pkl · error · ConversionException

Failed to convert `pkl.base#String` to `org.pkl.core.Version

Error message

Failed to convert `pkl.base#String` to `org.pkl.core.Version`.

What it means

Thrown by Conversions.pStringToVersion when mapping a Pkl `pkl.base#String` to `org.pkl.core.Version`. The string does not conform to semantic versioning syntax, so `Version.parse(value)` throws IllegalArgumentException, wrapped in a ConversionException.

Source

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

              builder.append(preRelease);
            }
            var build = value.get("build");
            if (build != null) {
              builder.append('+');
              builder.append(build);
            }
            return builder.toString();
          });

  public static final Conversion<String, Version> pStringToVersion =
      Conversion.of(
          PClassInfo.String,
          Version.class,
          (value, mapper) -> {
            try {
              return Version.parse(value);
            } catch (IllegalArgumentException e) {
              throw new ConversionException(
                  "Failed to convert `pkl.base#String` to `org.pkl.core.Version`.", e);
            }
          });

  /**
   * Identity conversions used when the Java representation of the Pkl type matches the target type
   * or when the target type is {@link Object}.
   */
  public static final Collection<Conversion<?, ?>> identities =
      List.of(
          Conversion.of(PClassInfo.Boolean, boolean.class, Converter.identity()),
          Conversion.of(PClassInfo.Boolean, Object.class, Converter.identity()),
          Conversion.of(PClassInfo.String, String.class, Converter.identity()),
          Conversion.of(PClassInfo.String, Object.class, Converter.identity()),
          Conversion.of(PClassInfo.Int, long.class, Converter.identity()),
          Conversion.of(PClassInfo.Int, Number.class, Converter.identity()),
          Conversion.of(PClassInfo.Int, Object.class, Converter.identity()),
          Conversion.of(PClassInfo.Float, double.class, Converter.identity()),

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Correct the string in the Pkl config to full strict semver: three numeric components, optional `-preRelease` and `+build`, no `v` prefix.
2. If the source provides a `v`-prefixed tag, strip the prefix before mapping.
3. Pre-validate with `org.pkl.core.Version.parse(value)` in a try/catch before mapping to get the parse failure details.
4. If only a partial version is available, normalize it (e.g. `1.2` -> `1.2.0`) at config-authoring time.

Example fix

// before (pkl)
appVersion = "v1.2"
// after (pkl)
appVersion = "1.2.0"

try { org.pkl.core.Version.parse(pklStringValue); } catch (IllegalArgumentException e) { throw new IllegalStateException("Config value is not a valid semver: " + pklStringValue); }

static boolean isValidSemver(String s) { try { org.pkl.core.Version.parse(s); return true; } catch (IllegalArgumentException e) { return false; } }

try { MyConfig cfg = mapper.map(module, MyConfig.class); } catch (ConversionException e) { throw new IllegalArgumentException("Version string in config must be strict semver (e.g. 1.2.3)", e.getCause()); }

When it happens

Trigger: Mapping to a target type with an `org.pkl.core.Version` field (or calling pStringToVersion directly) where the Pkl string is not a valid semver: missing components (`"1.2"`), a leading `v` prefix (`"v1.2.3"`), non-numeric components, or invalid pre-release/build metadata formatting.

Common situations: Config values copied from tags like `v2.0.0`; loosely formatted versions like `1.2` or `1.2.3-beta.01` (leading zeros in pre-release identifiers are invalid per semver); placeholders like `latest`.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Failed to convert `pkl.semver#Version` to `org.pkl.core.Vers
• Failed to convert `pkl.base#String` to `java.net.URI`.
• Failed to convert `pkl.base#String` to `java.net.URL`.
• Failed to convert `pkl.base#String` to `java.nio.file.Path`.
• Failed to convert `pkl.base#String` to `java.util.regex.Patt

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