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