oracle/graal · error · IllegalArgumentException

unknown encoding '%s'. Supported encodings are: UTF-8,UTF-16

Error message

unknown encoding '%s'. Supported encodings are: UTF-8,UTF-16,UTF-16-RAW,UTF-32,BYTES,LATIN-1

What it means

The TRegex 'Encoding' option (RegexOptions.EncodingOption) accepts only UTF-8, UTF-16, UTF-16-RAW, UTF-32, BYTES, LATIN-1. Its OptionType converter calls Encoding.getEncoding(name) and throws IllegalArgumentException for any other string.

Source

Thrown at regex/src/com.oracle.truffle.regex/src/com/oracle/truffle/regex/RegexOptions.java:241

        RegexFlavor get() {
            return FLAVOR_CACHE[ordinal()];
        }
    }

    private static RegexFlavor getDefaultFlavor() {
        return FlavorOption.ECMAScript.get();
    }

    @Option(category = OptionCategory.USER, stability = OptionStability.STABLE, help = "Regex flavor to use.", usageSyntax = "ECMAScript|JavaUtilPattern|OracleDB|Python|Ruby") //
    public static final OptionKey<FlavorOption> Flavor = new OptionKey<>(FlavorOption.ECMAScript);

    public static final String ENCODING_NAME = "Encoding";

    @Option(name = "Encoding", category = OptionCategory.USER, stability = OptionStability.STABLE, help = "Input string encoding.", usageSyntax = "UTF-8|UTF-16|UTF-16-RAW|UTF-32|BYTES|LATIN-1") //
    public static final OptionKey<Encoding> EncodingOption = new OptionKey<>(Encoding.UTF_16_RAW, new OptionType<>("Encoding", name -> {
        Encoding enc = Encoding.getEncoding(name);
        if (enc == null) {
            throw new IllegalArgumentException(String.format("unknown encoding '%s'. Supported encodings are: UTF-8,UTF-16,UTF-16-RAW,UTF-32,BYTES,LATIN-1", name));
        }
        return enc;
    }));

    public static final String PYTHON_METHOD_NAME = "PythonMethod";
    public static final String MATCHING_MODE_NAME = "MatchingMode";
    public static final String MATCHING_MODE_SEARCH = "search";
    public static final String MATCHING_MODE_MATCH = "match";
    public static final String MATCHING_MODE_FULLMATCH = "fullmatch";
    private static final String[] MATCHING_MODE_OPTIONS = {MATCHING_MODE_SEARCH, MATCHING_MODE_MATCH, MATCHING_MODE_FULLMATCH};

    @Option(category = OptionCategory.USER, stability = OptionStability.STABLE, help = "Regex matching mode. Supported modes are: " +
                    "'search': Default. Search for a match anywhere in the input string. " +
                    "'match': Anchor match at starting index. " +
                    "'fullmatch': Anchor match at starting and end index.", usageSyntax = "search|match|fullmatch") //
    public static final OptionKey<MatchingMode> MatchingMode = new OptionKey<>(com.oracle.truffle.regex.tregex.parser.MatchingMode.search);

    public static final String PYTHON_LOCALE_NAME = "PythonLocale";

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Use one of the exact supported spellings: UTF-8, UTF-16, UTF-16-RAW, UTF-32, BYTES, LATIN-1.
2. If the value comes from user config, validate it against the supported list before starting the Context and fail with a helpful message.
3. Map friendly aliases (e.g. 'utf8' -> 'UTF-8') in your own config layer before forwarding to the engine.

Example fix

// before
Context ctx = Context.newBuilder().option("regex.Encoding", "UTF8").build(); // throws

// after
Context ctx = Context.newBuilder().option("regex.Encoding", "UTF-8").build();

import java.util.Set;
private static final Set<String> TREGEX_ENCODINGS = Set.of("UTF-8", "UTF-16", "UTF-16-RAW", "UTF-32", "BYTES", "LATIN-1");

static String checkEncoding(String name) {
    if (!TREGEX_ENCODINGS.contains(name)) {
        throw new IllegalArgumentException("regex.Encoding must be one of " + TREGEX_ENCODINGS + ", got: " + name);
    }
    return name;
}

When it happens

Trigger: Setting the polyglot/regex option 'regex.Encoding' to an unsupported value, e.g. 'UTF8', 'utf-16le', 'ascii', or 'UTF_16_RAW' (wrong separator/case/spelling not recognized by the lookup).

Common situations: Config files migrated from other engines whose encoding names differ (e.g. ICU/ICU4J or Python codecs names); typos or hyphen/underscore confusion; new scripts passing options via Context.newBuilder().option("regex.Encoding", ...).

Related errors

• LIRInstructionVerifierPath is not supported in native image
• Invalid option
• No inlining policy provider with provided name:
• invalid double value: "%s"
• no choice named '%s'

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