apple/pkl · error · ConversionException

Failed to convert `pkl.base#String` to `java.util.regex.Patt

Error message

Failed to convert `pkl.base#String` to `java.util.regex.Pattern`.

What it means

Thrown by Conversions.pStringToPattern when mapping a Pkl `pkl.base#String` to a `java.util.regex.Pattern`. The string is not a syntactically valid Java regular expression, so `Pattern.compile(value)` throws PatternSyntaxException, wrapped in a ConversionException.

Source

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

          (value, mapper) -> {
            try {
              return Path.of(value);
            } catch (InvalidPathException e) {
              throw new ConversionException(
                  "Failed to convert `pkl.base#String` to `java.nio.file.Path`.", e);
            }
          });

  /** Conversion from {@code pkl.base#String} to {@link Pattern}. */
  public static final Conversion<String, Pattern> pStringToPattern =
      Conversion.of(
          PClassInfo.String,
          Pattern.class,
          (value, mapper) -> {
            try {
              return Pattern.compile(value);
            } catch (PatternSyntaxException e) {
              throw new ConversionException(
                  "Failed to convert `pkl.base#String` to `java.util.regex.Pattern`.", e);
            }
          });

  /** Conversion from {@code pkl.base#Regex} to {@link String}. */
  public static final Conversion<Pattern, String> pRegexToString =
      Conversion.of(PClassInfo.Regex, String.class, (value, mapper) -> value.pattern());

  /** Conversion from {@code pkl.base#Duration} to {@link java.time.Duration}. */
  public static final Conversion<Duration, java.time.Duration> pDurationToDuration =
      Conversion.of(
          PClassInfo.Duration, java.time.Duration.class, (value, mapper) -> value.toJavaDuration());

  /** Conversion from {@code pkl.semver#Version} to {@link Version}. */
  // Cannot leave this to `ConverterFactories.pObjectToDataObject`
  // because `Version` is part of pkl-core and thus cannot be annotated with `@Named`.
  public static final Conversion<PObject, Version> pVersionToVersion =
      Conversion.of(

View on GitHub (pinned to f3efcbfc9b)

Solutions

Fix the regex string in the Pkl config: balance parentheses/brackets, remove dangling backslashes, and ensure quantifiers follow a valid element.
Translate non-Java regex flavor constructs to java.util.regex equivalents (e.g. `(?:...)` named groups `(?<name>...)`).
Pre-validate with `Pattern.compile(value)` in a try/catch before mapping to get the exact error index and description.
If a glob is intended, convert it to a regex (e.g. quote literals and replace `*` with `.*`) before mapping.

Example fix

// before (pkl)
includePattern = "*.(txt|log"
// after (pkl)
includePattern = ".*\\.(txt|log)"

Defensive patterns

Strategy: validation

Validate before calling

try { java.util.regex.Pattern.compile(pklStringValue); } catch (java.util.regex.PatternSyntaxException e) { throw new IllegalStateException("Invalid regex in config: " + pklStringValue + " (" + e.getDescription() + " near index " + e.getIndex() + ")"); }

Type guard

static boolean isValidRegex(String s) { try { java.util.regex.Pattern.compile(s); return true; } catch (java.util.regex.PatternSyntaxException e) { return false; } }

Try / catch

try { MyConfig cfg = mapper.map(module, MyConfig.class); } catch (ConversionException e) { log.error("Config regex does not compile: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage()); }

Prevention

Test regex strings in a Java regex tool before adding them to config
Balance all groups and character classes; escape literal special chars with \\
Convert globs (*.log) to regex explicitly
Beware of regex flavors: java.util.regex is not full PCRE

When it happens

Trigger: Mapping to a target type with a `java.util.regex.Pattern` field (or calling Conversions.pStringToPattern directly) where the Pkl string has unbalanced groups/brackets, a dangling escape (`"\\"`), a bad quantifier (`"*abc"`, `"a{2,1}"`), or uses syntax from another regex flavor unsupported by java.util.regex (e.g. lookbehind of unbounded length on old JDKs, `\p{...}` sets not supported).

Common situations: Patterns copied from PCRE/JS/Python flavors (e.g. `\d` is fine but `(?'name'...)` is not); hand-edited patterns missing a closing `)` or `]`; shell glob patterns (`*.log`) mistakenly used where a regex is required.

Related errors

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