git.iko.soy/urbit.org
on 37de759 help sign in
urbit.org/reference/hoon-errors.md
180 lines 5.7 kB history raw
1+++
2title = "Hoon Errors"
3weight = 6
4template = "doc.html"
5+++
6Ideally your Hoon works perfectly the first time. But...
8## Syntax errors
10When you get a syntax error, you'll see a message like
12```
13syntax error at [10 12]
14```
16This is a line and column number; more exactly, the line and
17column of the first byte the parser couldn't interpret as part of
18a correct Hoon file. These values are always correct.
20Usually, the line and column tell you everything you need to
21know. But the worst-case scenario for a syntax error is that,
22somewhere above, you've confused Hoon's tall form by using the
23wrong fanout for a rune. For example, `%+` ([**cenlus**](@/docs/reference/hoon-expressions/rune/cen.md#cenlus),
24a function call whose sample is a cell) has three subhoons:
26```hoon
27%+ foo
28 bar
29baz
30```
32But if you make a mistake and write
34```hoon
35%+ foo
36bar
37```
39the parser will eat the next reference below and try to treat it as a
40part of the `%+`. This can cause a cascading error somewhere
41below, usually stopped by a `==` or `--`.
43When this happens, don't panic! Binary search actually works
44quite well. Any reference can be stubbed out as `!!`. Find the
45prefix of your file that compiles, then work forward until
46the actual error appears.
48## Semantic errors
50Now your code parses but doesn't compile.
52### Turn on debugging
54Your first step should be to put a `!:` ("zapcol") rune at the
55top of the file. This is like calling the C compiler with `-g`;
56it tells the Hoon compiler to generate tracing references.
58Bear in mind that `!:` breaks tail-call optimization. This is a
59bug, but a relatively low-priority bug. `!.` turns off `!:`.
60Note that `!:` and `!.` are reference-level, not file-level; you can
61wrap any reference in either.
63### Error trace
65If you have `!:` on, you'll see an error trace, like
67```
68/~zod/home/0/gen/hello:<[7 3].[11 21]>
69/~zod/home/0/gen/hello:<[8 1].[11 21]>
70/~zod/home/0/gen/hello:<[9 1].[11 21]>
71/~zod/home/0/gen/hello:<[10 1].[11 21]>
72/~zod/home/0/gen/hello:<[11 1].[11 21]>
73/~zod/home/0/gen/hello:<[11 7].[11 21]>
74nest-fail
75```
77The bottom of this trace is the line and column of the reference which
78failed to compile, then the cause of the error (`nest-fail`).
80Hoon does not believe in inundating you with possibly irrelevant
81debugging information. Your first resort is always to just look
82at the code and try to figure out what's wrong. This practice
83strengthens your Hoon muscles.
85(Consider the opposite extreme; imagine if you had a magic bot
86that always fixed your compiler errors for you. Pro: no time
87wasted on compiler errors. Con: you never learn Hoon.)
89## Common errors
91Moral fiber is all very well and good, but sometimes you're
92stumped. Couldn't the compiler help a little? These messages do
93mean something. Here are the three most common:
95### `nest-fail`
97This is a type mismatch (`nest` is the Hoon typechecker). It
98means you tried to pound a square peg into a round hole.
100What was the peg and what was the hole? Hoon doesn't tell you by
101default, because moral fiber, and also because in too many cases
102trivial errors lead to large intimidating dumps. However, you
103can use the `~!` rune ([**sigzap**](@/docs/reference/hoon-expressions/rune/sig.md#sigzap)) to print the type of any hoon in your stack trace.
105For instance, you wrote `(foo bar)` and got a `nest-fail`. Change
106your code to be:
108```hoon
109~! bar
110~! +6.foo
111(foo bar)
112```
114You'll get the same `nest-fail`, but this will show the type of
115`bar`, then the type of the sample of the `foo` gate.
117### `find.foo`
119A `find.foo` error means limb `foo` wasn't found in the subject.
120In other words, "undeclared variable."
122The most common subspecies of `find` error is `find.$`, meaning
123the empty name `$` was not found. This often happens when you
124use a reference that does not produce a gate/mold, as a gate/mold. For
125instance, `(foo bar)` will give `find.$` if `foo` is not actually a
126function.
128### `mint-vain` and `mint-lost`
130These are errors caused by type inference in pattern matching.
131`mint-vain` means this hoon is never executed. `mint-lost` means there's a case in a `?-` ([**wuthep**](@/docs/reference/hoon-expressions/rune/wut.md#wuthep)) that isn't handled.
133## Runtime crashes
135If your code crashes at runtime or overflows the stack, you'll
136see a stack trace that looks just like the trace above. Don't
137confuse runtime crashes with compilation errors, though.
139If your code goes into an infinite loop, kill it with `ctrl-c` (you'll
140need to be developing on the local console; otherwise, the
141infinite loop will time out either too slowly or too fast). The
142stack trace will show what your code was doing when interrupted.
144The counterpart of `~!` for runtime crashes is `~|`
145([**sigbar**](@/docs/reference/hoon-expressions/rune/sig.md#sigbar)):
147```hoon
148~| foo
149(foo bar)
150```
152If `(foo bar)` crashes, the value of `foo` is printed in the
153stack trace. Otherwise, the `~|` has no effect.
155## Debugging printfs
157The worst possibility, of course, is that your code runs but does
158the wrong thing. This is relatively unusual in a typed
159functional language, but it still happens.
161`~&` ([**sigpam**](@/docs/reference/hoon-expressions/rune/sig.md#sigpam)) is Hoon's debugging printf.
162This pretty-prints its argument:
164```hoon
165~& foo
166(foo bar)
167```
169will always print `foo` every time it executes. A variant is
170`~?` ([**sigwut**](@/docs/reference/hoon-expressions/rune/sig.md#sigwut)), which prints only if a condition is
171true:
173```hoon
174~? =(37 (lent foo)) foo
175(foo bar)
176```
178For now, you need to be on the local console to see these debug
179printfs (which are implemented by interpreter hints). This is a
180bug and, like all bugs, will be fixed at some point.