git.iko.soy/urbit.org
on 3fee830 help sign in
urbit.org/docs/programming/troubleshooting.md
186 lines 5.5 kB history raw
1---
2sort: 10
3---
5# Troubleshooting
7Ideally your Hoon works perfectly the first time. But...
9## Syntax errors
11When you get a syntax error, you'll see a message like
13```
14syntax error: 10 12
15```
17This is a line and column number; more exactly, the line and
18column of the first byte the parser couldn't interpret as part of
19a correct Hoon file. These values are always correct.
21Usually, the line and column tell you everything you need to
22know. But the worst-case scenario for a syntax error is that,
23somewhere above, you've confused Hoon's tall form by using the
24wrong fanout for a rune. For example, `%+` (`:calt`, a function
25call whose sample is a cell) has three subtwigs:
27```
28%+ foo
29 bar
30baz
31```
33But if you make a mistake and write
35```
36%+ foo
37bar
38```
40the parser will eat the next twig below and try to treat it as a
41part of the `%+`. This can cause a cascading error somewhere
42below, usually stopped by a `==` or `--`.
44When this happens, don't panic! Binary search actually works
45quite well. Any twig can be stubbed out as `!!`. Find the
46prefix of your file that compiles, then work forward until
47the actual error appears.
49## Semantic errors
51Now your code parses but doesn't compile.
53### Turn on debugging
55Your first step should be to put a `!:` ("zapcol") rune at the
56top of the file. This is like calling the C compiler with `-g`;
57it tells the Hoon compiler to generate tracing twigs.
59Bear in mind that `!:` breaks tail-call optimization. This is a
60bug, but a relatively low-priority bug. `!.` turns off `!:`.
61Note that `!:` and `!.` are twig-level, not file-level; you can
62wrap any twig in either.
64### Error trace
66If you have `!:` on, you'll see an error trace, like
68```
69/~zod/home/0/gen/hello:<[7 3].[11 21]>
70/~zod/home/0/gen/hello:<[8 1].[11 21]>
71/~zod/home/0/gen/hello:<[9 1].[11 21]>
72/~zod/home/0/gen/hello:<[10 1].[11 21]>
73/~zod/home/0/gen/hello:<[11 1].[11 21]>
74/~zod/home/0/gen/hello:<[11 7].[11 21]>
75nest-fail
76```
78The bottom of this trace is the line and column of the twig which
79failed to compile, then the cause of the error (`nest-fail`).
81Hoon does not believe in inundating you with possibly irrelevant
82debugging information. Your first resort is always to just look
83at the code and try to figure out what's wrong. This practice
84strengthens your Hoon muscles.
86(Consider the opposite extreme; imagine if you had a magic bot
87that always fixed your compiler errors for you. Pro: no time
88wasted on compiler errors. Con: you never learn Hoon.)
90## Common errors
92Moral fiber is all very well and good, but sometimes you're
93stumped. Couldn't the compiler help a little? These messages do
94mean something. Here are the three most common:
96### `nest-fail`
98This is a type mismatch (`nest` is the Hoon typechecker). It
99means you tried to pound a square peg into a round hole.
101What was the peg and what was the hole? Hoon doesn't tell you by
102default, because moral fiber, and also because in too many cases
103trivial errors lead to large intimidating dumps. However, you
104can use the `~!` rune ("sigzap", `:peep`) to print the type of
105any twig in your stack trace.
107For instance, you wrote `(foo bar)` and got a `nest-fail`. Change
108your code to be:
110```
111~! bar
112~! +6.foo
113(foo bar)
114```
116You'll get the same `nest-fail`, but this will show the type of
117`bar`, then the type of the sample of the `foo` gate.
119### `find.foo`
121A `find.foo` error means limb `foo` wasn't found in the subject.
122In other words, "undeclared variable."
124The most common subspecies of `find` error is `find.$`, meaning
125the empty name `$` was not found. This often happens when you
126use a twig that does not produce a gate/mold, as a gate/mold.
128For instance, `(foo bar)` will give `find.$` if `foo` is not
129actually a function. `?=([%foo %bar] baz)` will give `find.$`,
130because `?=` ("wuttis", `:fits`) needs a mold rather than a seed
131(you probably meant `?=({$foo $bar} baz)`).
133### `mint-vain` and `mint-lost`
135These are errors caused by type inference in pattern matching.
136`mint-vain` means this twig is never executed. `mint-lost` means
137there's a case in a `?-` ("wuthep", `:case`) that isn't handled.
139## Runtime crashes
141If your code crashes at runtime or overflows the stack, you'll
142see a stack trace that looks just like the trace above. Don't
143confuse runtime crashes with compilation errors, though.
145If your code goes into an infinite loop, kill it with `^C` (you'll
146need to be developing on the local console; otherwise, the
147infinite loop will time out either too slowly or too fast). The
148stack trace will show what your code was doing when interrupted.
150The counterpart of `~!` for runtime crashes is `~|` ("sigbar",
151`:show`):
153```
154~| foo
155(foo bar)
156```
158If `(foo bar)` crashes, the value of `foo` is printed in the
159stack trace. Otherwise, the `~|` has no effect.
161## Debugging printfs
163The worst possibility, of course, is that your code runs but does
164the wrong thing. This is relatively unusual in a typed
165functional language, but it still happens.
167`~&` ("sigpam", `:dump`) is Hoon's debugging printf. This
168pretty-prints its argument:
170```
171~& foo
172(foo bar)
173```
175will always print `foo` every time it executes. A variant is
176`~?` ("sigwut", `:warn`), which prints only if a condition is
177true:
179```
180~? =(37 (lent foo)) foo
181(foo bar)
182```
184For now, you need to be on the local console to see these debug
185printfs (which are implemented by interpreter hints). This is a
186bug and, like all bugs, will be fixed at some point.