gleam-lang/gleam · error

UTF-codepoint pattern matching is not supported

Error message

UTF-codepoint pattern matching is not supported

What it means

This Gleam compiler error occurs when a UTF codepoint segment option (utf8_codepoint, utf16_codepoint, or utf32_codepoint) is used inside a bit array PATTERN while compiling to JavaScript. The compiler's type_options function explicitly rejects this combination because codepoint pattern matching is not implemented on the JavaScript target.

Solutions

1. Rewrite the pattern to match on the bit array as bytes/bits without a utf-codepoint option, and decode the codepoint manually in the branch body
2. Split target-specific code with conditional compilation or keep codepoint pattern matching in modules only compiled for Erlang
3. Use string pattern matching or a binary-to-string conversion before matching instead of codepoint-level bit array patterns

Example fix

// before (JS target)
let assert <<"a":utf8_codepoint, rest:bytes>> = data
// after
let assert <<_, rest:bytes>> = data
let ch = bit_array.to_string(<<>>)
// or restrict this module/function to the Erlang target

// Before using a utf-codepoint pattern option, check the target at build time
// gleam: only use `utf8_codepoint`/`utf16_codepoint`/`utf32_codepoint` in patterns
// when targeting erlang. For JS, guard with a runtime decode instead:
fn uses_codepoint_patterns(target: String) -> Bool {
  target != "javascript"
}

When it happens

Trigger: Compiling a bit array pattern segment that carries a Utf8Codepoint, Utf16Codepoint, or Utf32Codepoint option when Target::JavaScript is selected and mode is TypeOptionsMode::Pattern. The same options in a bit array value expression are fine.

Common situations: Cross-target projects that work on Erlang but fail when someone adds a JS target; developers porting binary-protocol parsing code (e.g. matching on UTF-8 string fragments) to JavaScript.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• ErrorType::OptionNotSupportedForTarget
• ErrorType::SegmentMustHaveSize
• aliased non constant value
• bytes must not be empty
• ErrorType::ConflictingEndiannessOptions

AI-assisted analysis of gleam-lang/gleam@15b07c7830 (2026-09-14). Data as JSON: /api/errors/03ecdf7a03ef1688. Report an issue: GitHub.

Appendix: source

Thrown at compiler-core/src/bit_array.rs:115

fn type_options<TypedValue>(
    input_options: &[BitArrayOption<TypedValue>],
    mode: TypeOptionsMode,
    must_have_size: bool,
    target: Target,
) -> Result<Arc<Type>, Error>
where
    TypedValue: GetLiteralValue,
{
    use BitArrayOption::*;

    let mut categories = SegmentOptionCategories::new();
    // Basic category checking
    for option in input_options {
        match option {
            Utf8Codepoint { .. } | Utf16Codepoint { .. } | Utf32Codepoint { .. }
                if mode == TypeOptionsMode::Pattern && target == Target::JavaScript =>
            {
                return err(
                    ErrorType::OptionNotSupportedForTarget {
                        target,
                        option: UnsupportedOption::UtfCodepointPattern,
                    },
                    option.location(),
                );
            }

            Bytes { .. }
            | Int { .. }
            | Float { .. }
            | Bits { .. }
            | Utf8 { .. }
            | Utf16 { .. }
            | Utf32 { .. }
            | Utf8Codepoint { .. }
            | Utf16Codepoint { .. }
            | Utf32Codepoint { .. } => {

View on GitHub (pinned to 15b07c7830)