{"record":{"id":"d9aa7c8f7b619400","repo":"apple/pkl","slug":"failed-to-convert-pkl-base-string-to-org-pkl-co","errorCode":null,"errorMessage":"Failed to convert `pkl.base#String` to `org.pkl.core.Version`.","messagePattern":"Failed to convert `pkl\\.base#String` to `org\\.pkl\\.core\\.Version`\\.","errorType":"exception","errorClass":"ConversionException","httpStatus":null,"severity":"error","filePath":"pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java","lineNumber":263,"sourceCode":"              builder.append(preRelease);\n            }\n            var build = value.get(\"build\");\n            if (build != null) {\n              builder.append('+');\n              builder.append(build);\n            }\n            return builder.toString();\n          });\n\n  public static final Conversion<String, Version> pStringToVersion =\n      Conversion.of(\n          PClassInfo.String,\n          Version.class,\n          (value, mapper) -> {\n            try {\n              return Version.parse(value);\n            } catch (IllegalArgumentException e) {\n              throw new ConversionException(\n                  \"Failed to convert `pkl.base#String` to `org.pkl.core.Version`.\", e);\n            }\n          });\n\n  /**\n   * Identity conversions used when the Java representation of the Pkl type matches the target type\n   * or when the target type is {@link Object}.\n   */\n  public static final Collection<Conversion<?, ?>> identities =\n      List.of(\n          Conversion.of(PClassInfo.Boolean, boolean.class, Converter.identity()),\n          Conversion.of(PClassInfo.Boolean, Object.class, Converter.identity()),\n          Conversion.of(PClassInfo.String, String.class, Converter.identity()),\n          Conversion.of(PClassInfo.String, Object.class, Converter.identity()),\n          Conversion.of(PClassInfo.Int, long.class, Converter.identity()),\n          Conversion.of(PClassInfo.Int, Number.class, Converter.identity()),\n          Conversion.of(PClassInfo.Int, Object.class, Converter.identity()),\n          Conversion.of(PClassInfo.Float, double.class, Converter.identity()),","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java#L245-L281","documentation":"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.","triggerScenarios":"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.","commonSituations":"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`.","solutions":["Correct the string in the Pkl config to full strict semver: three numeric components, optional `-preRelease` and `+build`, no `v` prefix.","If the source provides a `v`-prefixed tag, strip the prefix before mapping.","Pre-validate with `org.pkl.core.Version.parse(value)` in a try/catch before mapping to get the parse failure details.","If only a partial version is available, normalize it (e.g. `1.2` -> `1.2.0`) at config-authoring time."],"exampleFix":"// before (pkl)\nappVersion = \"v1.2\"\n// after (pkl)\nappVersion = \"1.2.0\"","handlingStrategy":"validation","validationCode":"try { org.pkl.core.Version.parse(pklStringValue); } catch (IllegalArgumentException e) { throw new IllegalStateException(\"Config value is not a valid semver: \" + pklStringValue); }","typeGuard":"static boolean isValidSemver(String s) { try { org.pkl.core.Version.parse(s); return true; } catch (IllegalArgumentException e) { return false; } }","tryCatchPattern":"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()); }","preventionTips":["Use full three-component versions (1.2.0, not 1.2)","Strip 'v' prefixes from git tags before writing to config","Avoid leading zeros in pre-release identifiers","Keep pre-release/build metadata in the dedicated fields, not the numeric parts"],"tags":["pkl","java","version","semver","conversion"],"backgroundTag":"invalid-argument-format","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}