31. Build errors

Level: intermediate · Reading time: 12 min · Prerequisite: book/chapters/30-faq.html · Track: supplemental · Maturity: draft · Last review: 2026-05-09

Prerequisites: book/chapters/30-faq.html. See also: book/chapters/30-faq.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Readers often see diagnostics as messages to memorize rather than structured signals tied to a failing contract.

Red Thread (Single Project)

One broken program produces one actionable error, then a corrected version restores the intended flow.

For what

This chapter helps the reader classify and use diagnostics instead of fearing them.

What you are going to do

You will read a valid example, a broken example, and the contract that the diagnostic is pointing back to.

Coherent example

space demo/diagnostics

proc safe_div(total: int, count: int) -> int {
  if count == 0 { give 0 }
  give total
}

Global explanation

A diagnostics chapter should explain the shape of a failure: what contract was expected, which surface broke it, and how to return to a valid program. The message is a pointer back to structure, not an isolated artifact.

Invalid case

proc bad_div(total: int, count: int) -> int {
  if count { give total }
  give 0
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Teaching diagnostics as a table of codes with no code story.
• Explaining only the message text, not the broken contract.
• Using overly large examples that hide the first real mistake.

Short exercise

Take the invalid example and reduce it until one diagnostic still reproduces the same contract failure.

Summary in 5 points

1. Diagnostics point back to a broken contract.
2. A valid and invalid pair is the right teaching unit.
3. Smaller repros are more educational than giant failing files.
4. The first useful question is what contract broke.
5. Actionable fixes start from structure, not from guesswork.