{"record":{"id":"03ecdf7a03ef1688","repo":"gleam-lang/gleam","slug":"utf-codepoint-pattern-matching-is-not-supported","errorCode":null,"errorMessage":"UTF-codepoint pattern matching is not supported","messagePattern":"UTF-codepoint pattern matching is not supported","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"compiler-core/src/bit_array.rs","lineNumber":115,"sourceCode":"fn type_options<TypedValue>(\n    input_options: &[BitArrayOption<TypedValue>],\n    mode: TypeOptionsMode,\n    must_have_size: bool,\n    target: Target,\n) -> Result<Arc<Type>, Error>\nwhere\n    TypedValue: GetLiteralValue,\n{\n    use BitArrayOption::*;\n\n    let mut categories = SegmentOptionCategories::new();\n    // Basic category checking\n    for option in input_options {\n        match option {\n            Utf8Codepoint { .. } | Utf16Codepoint { .. } | Utf32Codepoint { .. }\n                if mode == TypeOptionsMode::Pattern && target == Target::JavaScript =>\n            {\n                return err(\n                    ErrorType::OptionNotSupportedForTarget {\n                        target,\n                        option: UnsupportedOption::UtfCodepointPattern,\n                    },\n                    option.location(),\n                );\n            }\n\n            Bytes { .. }\n            | Int { .. }\n            | Float { .. }\n            | Bits { .. }\n            | Utf8 { .. }\n            | Utf16 { .. }\n            | Utf32 { .. }\n            | Utf8Codepoint { .. }\n            | Utf16Codepoint { .. }\n            | Utf32Codepoint { .. } => {","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/gleam-lang/gleam/blob/3e3c5ddc08f0e23b3f7e5331506920b884007b5f/compiler-core/src/bit_array.rs#L97-L133","documentation":"Gleam compile error (TypeError::OptionNotSupportedForTarget): when type-checking bit array segments in pattern position that use utf8_codepoint, utf16_codepoint, or utf32_codepoint while compiling for the JavaScript target. The guard mode == TypeOptionsMode::Pattern && target == Target::JavaScript fires because the JS codegen cannot destructure UTF codepoint segments in patterns (it can still construct them in expressions); the compiler rejects the segment with UnsupportedOption::UtfCodepointPattern and points at the offending option.","triggerScenarios":"Writing a case pattern like '<<c:utf8_codepoint, rest:bits>>' and building/checking with target = \"javascript\" in gleam.toml or --target javascript. The same pattern compiles fine on the Erlang target.","commonSituations":"Porting string/binary parsing code originally written for the Erlang target to JavaScript; sharing parsing modules between targets; following Erlang-style binary-matching idioms.","solutions":["Rewrite the pattern without codepoint options: match the remaining bytes (e.g. <<rest:bytes>>) and decode with bit_array.to_string / string functions afterwards","Match on Gleam String values directly where possible, since Gleam strings are UTF-8 and support pattern matching via case","Keep such modules on the Erlang target by setting target = \"erlang\" if JS support is not required"],"exampleFix":"// before (panics only at compile time on the JavaScript target)\n// gleam.toml: target = \"javascript\"\npub fn first_codepoint(s: BitArray) {\n  case s {\n    <<codepoint:utf8_codepoint, rest:bits>> -> Ok(#(codepoint, rest))\n    _ -> Error(Nil)\n  }\n}\n\n// after: match bytes, decode as UTF-8 string instead\npub fn first_codepoint(s: BitArray) {\n  case s {\n    <<first:bytes-size(1), rest:bits>> ->\n      case bit_array.to_string(<<first, rest:bits>>) {\n        Ok(string) -> string_pop_grapheme(string)\n        Error(Nil) -> Error(Nil)\n      }\n    _ -> Error(Nil)\n  }\n}","handlingStrategy":"validation","validationCode":"# catch target-specific bit array rejections before shipping: check both targets in CI\ngleam check --target erlang && gleam check --target javascript","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid utf8_codepoint/utf16_codepoint/utf32_codepoint in bit array patterns of cross-target code; match bytes or use String matching instead","Add 'gleam check --target javascript' to CI for projects that also target Erlang","Remember the restriction is pattern-only and JavaScript-only: construction and the Erlang target remain valid"],"tags":["bit-array","javascript-target","compile-error","pattern-matching","utf8","gleam"],"backgroundTag":"unsupported-option-for-target","analyzedSha":"3e3c5ddc08f0e23b3f7e5331506920b884007b5f","analyzedAt":"2026-08-20T06:21:11.390Z","contentChangedAt":"2026-08-20T06:21:11.390Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}