gleam-lang/gleam · error

list has a type argument

Error message

list has a type argument

What it means

In exhaustiveness checking, when a match branch's subject type is the prelude `List`, the compiler extracts the element type with `arguments.first().expect("list has a type argument")`. The type system guarantees `List` is always parameterised by exactly one element type, so `arguments` should never be empty; the `expect` enforces that invariant and panics if a `List`-typed `Type::Named` arrives with zero type arguments.

Solutions

1. Simplify/rewrite the `case` expression on the list and rebuild to confirm it is not a cache artifact (`gleam clean` then rebuild)
2. Upgrade Gleam and ensure `gleam_stdlib` is current (`gleam deps update`) so type metadata matches the compiler's expectations
3. If reproducible with minimal code, file a compiler bug including the pattern-match that triggers it

Example fix

// before
let l = [1, 2, 3]
case l { [] -> 0 | [x, ..] -> x }  // panic on affected versions
// after (workaround: update compiler/stdlib, or avoid the triggering shape)
let l = [1, 2, 3]
gleam:list.first(l)  // use stdlib helpers while the bug is unresolved

// pre-flight: clean stale artifacts and ensure stdlib matches before compiling
// gleam clean && gleam deps update && gleam build

let status = Command::new("gleam").arg("build").status();
if !status.map(|s| s.success()).unwrap_or(false) {
    eprintln!("build panicked or failed; run `gleam clean` and retry");
}

When it happens

Trigger: Running exhaustiveness analysis (any `case` expression matching on a list) when the checker sees `Type::Named { name: "List", arguments: [] }` — caused by a compiler bug in type instantiation, an improperly constructed type from FFI/external type declarations, or a stale/incompatible build of `gleam_stdlib` type metadata.

Common situations: Appears as a compiler panic while compiling `case` expressions over lists, usually after a compiler upgrade or when custom tooling/FFI constructs a `List` type without its type parameter.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Custom type variants must exist
• at least one choice
• bit array compilation with no choice
• check to already be a choice
• empty bit array test

AI-assisted analysis of gleam-lang/gleam@49f8762da5 (2026-09-14). Data as JSON: /api/errors/8fe0163f2b17aa86. Report an issue: GitHub.

Appendix: source

Thrown at compiler-core/src/exhaustiveness.rs:966

        match collapse_links(self.type_.clone()).as_ref() {
            Type::Fn { .. } | Type::Var { .. } => BranchMode::Infinite,
            Type::Named { module, name, .. }
                if is_prelude_module(module)
                    && (name == "Int"
                        || name == "Float"
                        || name == "BitArray"
                        || name == "String") =>
            {
                BranchMode::Infinite
            }

            Type::Named {
                module,
                name,
                arguments,
                ..
            } if is_prelude_module(module) && name == "List" => BranchMode::List {
                inner_type: arguments.first().expect("list has a type argument").clone(),
            },

            Type::Tuple { elements } => BranchMode::Tuple {
                elements: elements.clone(),
            },

            Type::Named {
                module,
                name,
                arguments,
                inferred_variant,
                ..
            } => {
                let constructors = ConstructorSpecialiser::specialise_constructors(
                    env.get_constructors_for_type(module, name)
                        .expect("Custom type variants must exist"),
                    arguments.as_slice(),
                    &env.current_module,

View on GitHub (pinned to 49f8762da5)