What causes "Unsupported Unicode character property escape" in oracle/graal?

Replace the unsupported property with an equivalent supported one or an explicit character class/range.

oracle/graal · error · IllegalArgumentException

Unsupported Unicode character property escape

Error message

Unsupported Unicode character property escape

What it means

When a regex uses a Unicode property escape like \p{...}, UnicodeProperties.evaluatePropertySpec normalizes the spec and looks it up in the compiled property database. If retrieveProperty returns null (unknown property/value combination after normalization), it throws IllegalArgumentException 'Unsupported Unicode character property escape'.

Source

Thrown at regex/src/com.oracle.truffle.regex/src/com/oracle/truffle/regex/charset/UnicodeProperties.java:141

    public CodePointSet unionOfProperties(CodePointSet initial, String... properties) {
        CodePointSetAccumulator acc = new CodePointSetAccumulator();
        if (initial != null) {
            acc.addSet(initial);
        }
        for (String property : properties) {
            acc.addSet(getProperty(property));
        }
        return acc.toCodePointSet();
    }

    /**
     * @param propertySpec *Normalized* Unicode character property specification (i.e. only
     *            abbreviated properties and property values)
     */
    private CodePointSet evaluatePropertySpec(String propertySpec) {
        CodePointSet prop = data.retrieveProperty(propertySpec);
        if (prop == null) {
            throw new IllegalArgumentException("Unsupported Unicode character property escape");
        }
        return prop;
    }

    /**
     * @param propertySpec *Normalized* Unicode character property specification (i.e. only
     *            abbreviated properties and property values)
     */
    private ClassSetContents evaluatePropertySpecStrings(String propertySpec) {
        ClassSetContents prop = data.retrievePropertyOfStrings(propertySpec);
        if (prop == null) {
            throw new IllegalArgumentException("Unsupported Unicode character property escape");
        }
        return prop;
    }

    private String normalizePropertySpec(String propertySpec) {
        int equals = propertySpec.indexOf('=');

View on GitHub (pinned to a66e9ccd1d)

Solutions

Replace the unsupported property with an equivalent supported one or an explicit character class/range.
Check which Unicode version/property set your TRegex build supports (UnicodeProperties data) and use only those names.
Upgrade GraalVM/TRegex so the property database matches the Unicode version your pattern targets.
For exotic properties, precompute the code point set yourself and build an explicit class.

Example fix

// before
Pattern p = compile("\\p{Grapheme_Cluster_Break=Extend}"); // not in property DB

// after
// approximate with explicit ranges / supported property
Pattern p = compile("[\\u0300-\\u036F\\u200C\\u200D]");

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check a property spec against the engine's supported set
boolean supported = props.isSupportedProperty("Grapheme_Cluster_Break");
// for enumerated forms: normalize then check, e.g. isSupportedScript / isSupportedGeneralCategory

Try / catch

try {
    return engine.compile(patternWithPropertyEscape);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unicode character property")) {
        return compileWithExplicitClassFallback(patternWithPropertyEscape);
    }
    throw e;
}

Prevention

Restrict patterns to properties of the Unicode version compiled into your TRegex build.
Replace exotic properties with explicit ranges generated offline.
When porting patterns between engines, diff their supported property lists first.

When it happens

Trigger: Compiling a pattern containing \p{UnknownProperty} or a property name/value alias not present in the Unicode data shipped with the engine, e.g. \p{Script=Foo} or a property introduced in a newer Unicode version than the database.

Common situations: Patterns written against a newer JDK's java.util.regex Unicode data (new properties like Emoji_* or newer script names) run on a GraalVM/TRegex build with older Unicode data; properties supported only by specific flavors (e.g. OtherProperties) used in a flavor that disables them.

Related errors

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/e9e68632ec883a01. Report an issue: GitHub.