gleam-lang/gleam · error

Term must exist

Error message

Term must exist

What it means

`Printer::print_terms` formats the compiled decision tree's terms for the 'unused/match-of-patterns never reached' diagnostics. For each subject it maps the subject id to a term index and does `terms.get(index).expect("Term must exist")`; it panics if a subject references a term index absent from the terms list. Subjects without a mapping are printed as `_`, so this only fails on corrupt/inconsistent mapping data.

Solutions

1. Keep `mapping` and `terms` in sync: if you filter/rebuild one, rebuild the other
2. Validate before printing: `mapping.values().all(|i| *i < terms.len())`
3. Treat missing indices like the None case (print `_`) if partial output is acceptable
4. If triggered by normal Gleam code, file a compiler bug with the case expression

Example fix

// before
let term = terms.get(index).expect("Term must exist");
// after
let Some(term) = terms.get(index) else {
    buffer.push('_');
    continue;
};

if mapping.values().any(|i| *i >= terms.len()) {
    return Err(Error::TermMappingInconsistent);
}

fn mapping_consistent(mapping: &HashMap<VariableId, usize>, terms: &[Term]) -> bool {
    mapping.values().all(|i| *i < terms.len())
}

When it happens

Trigger: Calling `print_terms` with a `mapping` that contains a subject id pointing to an index >= `terms.len()` — e.g. after filtering terms without updating the mapping, or when combining a mapping built against a different term list.

Common situations: Seen by compiler contributors when post-processing compile case results (e.g. trimming terms for diagnostics) or when caching decision trees across environments.

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

• case with no subjects
• Custom type constructor exist for type
• Custom type constructor must have custom type kind
• Error printing produced invalid utf8
• Should be a named type

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

Appendix: source

Thrown at compiler-core/src/exhaustiveness/printer.rs:44

            names,
        }
    }

    pub fn print_terms(
        &self,
        subjects: &[Variable],
        terms: &[Term],
        mapping: &HashMap<usize, usize>,
    ) -> EcoString {
        let mut buffer = EcoString::new();
        for (i, subject) in subjects.iter().enumerate() {
            if i != 0 {
                buffer.push_str(", ");
            }

            match mapping.get(&subject.id) {
                Some(&index) => {
                    let term = terms.get(index).expect("Term must exist");
                    self.print(term, terms, mapping, &mut buffer);
                }
                None => buffer.push('_'),
            }
        }
        buffer
    }

    fn print(
        &self,
        term: &Term,
        terms: &[Term],
        mapping: &HashMap<usize, usize>,
        buffer: &mut EcoString,
    ) {
        match term {
            Term::Variant {
                name,

View on GitHub (pinned to 15b07c7830)