git.iko.soy/urbit.org
on 6d45ede help sign in
urbit.org/docs/hoon/troubleshooting.md
189 lines 5.5 kB history raw
1---
2navhome: /docs
3sort: 12
4title: Troubleshooting
5next: true
6---
8# Troubleshooting
10Ideally your Hoon works perfectly the first time. But...
12## Syntax errors
14When you get a syntax error, you'll see a message like
16```
17syntax error: 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, `%+` (`:calt`, a function
28call whose sample is a cell) has three subtwigs:
30```
31%+ foo
32 bar
33baz
34```
36But if you make a mistake and write
38```
39%+ foo
40bar
41```
43the parser will eat the next twig 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 twig 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
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 twigs.
62Bear in mind that `!:` breaks tail-call optimization. This is a
63bug, but a relatively low-priority bug. `!.` turns off `!:`.
64Note that `!:` and `!.` are twig-level, not file-level; you can
65wrap any twig in either.
67### Error trace
69If you have `!:` on, you'll see an error trace, like
71```
72/~zod/home/0/gen/hello:<[7 3].[11 21]>
73/~zod/home/0/gen/hello:<[8 1].[11 21]>
74/~zod/home/0/gen/hello:<[9 1].[11 21]>
75/~zod/home/0/gen/hello:<[10 1].[11 21]>
76/~zod/home/0/gen/hello:<[11 1].[11 21]>
77/~zod/home/0/gen/hello:<[11 7].[11 21]>
78nest-fail
79```
81The bottom of this trace is the line and column of the twig which
82failed to compile, then the cause of the error (`nest-fail`).
84Hoon does not believe in inundating you with possibly irrelevant
85debugging information. Your first resort is always to just look
86at the code and try to figure out what's wrong. This practice
87strengthens your Hoon muscles.
89(Consider the opposite extreme; imagine if you had a magic bot
90that always fixed your compiler errors for you. Pro: no time
91wasted on compiler errors. Con: you never learn Hoon.)
93## Common errors
95Moral fiber is all very well and good, but sometimes you're
96stumped. Couldn't the compiler help a little? These messages do
97mean something. Here are the three most common:
99### `nest-fail`
101This is a type mismatch (`nest` is the Hoon typechecker). It
102means you tried to pound a square peg into a round hole.
104What was the peg and what was the hole? Hoon doesn't tell you by
105default, because moral fiber, and also because in too many cases
106trivial errors lead to large intimidating dumps. However, you
107can use the `~!` rune ("sigzap", `:peep`) to print the type of
108any twig in your stack trace.
110For instance, you wrote `(foo bar)` and got a `nest-fail`. Change
111your code to be:
113```
114~! bar
115~! +6.foo
116(foo bar)
117```
119You'll get the same `nest-fail`, but this will show the type of
120`bar`, then the type of the sample of the `foo` gate.
122### `find.foo`
124A `find.foo` error means limb `foo` wasn't found in the subject.
125In other words, "undeclared variable."
127The most common subspecies of `find` error is `find.$`, meaning
128the empty name `$` was not found. This often happens when you
129use a twig that does not produce a gate/mold, as a gate/mold.
131For instance, `(foo bar)` will give `find.$` if `foo` is not
132actually a function. `?=([%foo %bar] baz)` will give `find.$`,
133because `?=` ("wuttis", `:fits`) needs a mold rather than a seed
134(you probably meant `?=({$foo $bar} baz)`).
136### `mint-vain` and `mint-lost`
138These are errors caused by type inference in pattern matching.
139`mint-vain` means this twig is never executed. `mint-lost` means
140there's a case in a `?-` ("wuthep", `:case`) that isn't handled.
142## Runtime crashes
144If your code crashes at runtime or overflows the stack, you'll
145see a stack trace that looks just like the trace above. Don't
146confuse runtime crashes with compilation errors, though.
148If your code goes into an infinite loop, kill it with `ctrl-c` (you'll
149need to be developing on the local console; otherwise, the
150infinite loop will time out either too slowly or too fast). The
151stack trace will show what your code was doing when interrupted.
153The counterpart of `~!` for runtime crashes is `~|` ("sigbar",
154`:show`):
156```
157~| foo
158(foo bar)
159```
161If `(foo bar)` crashes, the value of `foo` is printed in the
162stack trace. Otherwise, the `~|` has no effect.
164## Debugging printfs
166The worst possibility, of course, is that your code runs but does
167the wrong thing. This is relatively unusual in a typed
168functional language, but it still happens.
170`~&` ("sigpam", `:dump`) is Hoon's debugging printf. This
171pretty-prints its argument:
173```
174~& foo
175(foo bar)
176```
178will always print `foo` every time it executes. A variant is
179`~?` ("sigwut", `:warn`), which prints only if a condition is
180true:
182```
183~? =(37 (lent foo)) foo
184(foo bar)
185```
187For now, you need to be on the local console to see these debug
188printfs (which are implemented by interpreter hints). This is a
189bug and, like all bugs, will be fixed at some point.