gleam-lang/gleam · error · ErrorType

ErrorType::TypeDoesNotAllowUnit

Error message

ErrorType::TypeDoesNotAllowUnit { type_: type_.label() }

What it means

The `unit` option (a size multiplier) cannot be combined with unicode string segments (`utf8`, `utf16`, `utf32` and their `_codepoint` variants). `type_options` detects a unicode-typed segment (via `is_unicode`) that also carries a `unit` option and raises this error at the `unit` option's location.

Solutions

1. Remove the `unit(N)` option from the unicode segment.
2. Control string segment length with a `size` option instead, e.g. `<<x:utf8-size(4)>>`.
3. If byte-level control is needed, use a bytes segment and encode/decode explicitly with `gleam/bit_array`.

Example fix

// before
let a = <<name:utf8-unit(2)>>
// after
let a = <<name:utf8-size(4)>>

// Do not attach unit(N) to utf8/utf16/utf32 segments.
let is_unicode = fn(t: String) -> Bool {
  ["Utf8", "Utf16", "Utf32", "Utf8Codepoint", "Utf16Codepoint", "Utf32Codepoint"]
  |> list.contains(t)
}
// if is_unicode(t) { skip unit option }

When it happens

Trigger: Writing `<<x:utf8-unit(2)>>` or `<<c:utf16_codepoint-unit(4)>>` — any unicode-typed segment with `unit(N)`, in an expression or a pattern.

Common situations: Trying to pad or control string segment widths the way integer segments are controlled; copying integer-segment option sets onto utf8 segments when migrating BEAM code.

Related errors

• ErrorType::SignednessUsedOnNonInt
• ErrorType::TypeDoesNotAllowSize
• ErrorType::ConstantSizeNotPositive
• ErrorType::FloatWithSize
• ErrorType::UnitMustHaveSize

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

Appendix: source

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

            ..
        } => {
            return err(
                ErrorType::SignednessUsedOnNonInt { type_: opt.label() },
                sign.location(),
            );
        }

        _ => {}
    }

    // utf8, utf16, utf32 exclude unit and size
    match categories {
        SegmentOptionCategories {
            type_: Some(type_),
            unit: Some(unit),
            ..
        } if is_unicode(type_) => {
            return err(
                ErrorType::TypeDoesNotAllowUnit {
                    type_: type_.label(),
                },
                unit.location(),
            );
        }

        SegmentOptionCategories {
            type_: Some(type_),
            size: Some(size),
            ..
        } if is_unicode(type_) => {
            return err(
                ErrorType::TypeDoesNotAllowSize {
                    type_: type_.label(),
                },
                size.location(),
            );

View on GitHub (pinned to 15b07c7830)