# Hoon Errors In this section we explore strategies for debugging and understanding what your Hoon code is doing. We cover common errors that Dojo may spit out, how to turn on debugging and verbose mode, and how to use debugging printfs. ## Syntax errors When you get a syntax error, you'll see a message like: ``` syntax error at [10 12] ``` This is a line and column number; more exactly, the line and column of the first byte the parser couldn't interpret as part of a correct Hoon file. These values are always correct. Usually, the line and column tell you everything you need to know. But the worst-case scenario for a syntax error is that, somewhere above, you've confused Hoon's tall form by using the wrong fanout for a rune. For example, `%+` ([**cenlus**](https://docs.urbit.org/rune/cen#cenlus), a function call whose sample is a cell) has three subhoons: ```hoon %+ foo bar baz ``` But if you make a mistake and write ... ```hoon %+ foo bar ``` ... the parser will eat the next reference below and try to treat it as a part of the `%+`. This can cause a cascading error somewhere below, usually stopped by a `==` or `--`. When this happens, don't panic! Binary search actually works quite well. Any reference can be stubbed out as `!!`. Find the prefix of your file that compiles, then work forward until the actual error appears. ## Semantic errors Now your code parses but doesn't compile. ### Turn on debugging or verbose mode Your first step should be to put a `!:` ("zapcol") rune at the top of the file. This is like calling the C compiler with `-g`; it tells the Hoon compiler to generate tracing references. Bear in mind that `!:` breaks tail-call optimization. This is a bug, but a relatively low-priority bug. `!.` turns off `!:`. Note that `!:` and `!.` are reference-level, not file-level; you can wrap any reference in either. You may also find it helpful to turn on verbose mode by entering `|verb` into Dojo, which prints (almost) everything happening in the kernel to the console. This is useful for performing stack trace. An extensive stack trace tutorial is [below](#stack-trace-tutorial). ### Error trace If you have `!:` on, you'll see an error trace, like: ``` /~zod/base/0/gen/hello:<[7 3].[11 21]> /~zod/base/0/gen/hello:<[8 1].[11 21]> /~zod/base/0/gen/hello:<[9 1].[11 21]> /~zod/base/0/gen/hello:<[10 1].[11 21]> /~zod/base/0/gen/hello:<[11 1].[11 21]> /~zod/base/0/gen/hello:<[11 7].[11 21]> nest-fail ``` The bottom of this trace is the line and column of the reference which failed to compile, then the cause of the error (`nest-fail`). Hoon does not believe in inundating you with possibly irrelevant debugging information. Your first resort is always to just look at the code and try to figure out what's wrong. This practice strengthens your Hoon muscles. (Consider the opposite extreme; imagine if you had a magic bot that always fixed your compiler errors for you. Pro: no time wasted on compiler errors. Con: you never learn Hoon.) ## Common errors Moral fiber is all very well and good, but sometimes you're stumped. Couldn't the compiler help a little? These messages do mean something. Here are the three most common: ### `nest-fail` This is a type mismatch (`nest` is the Hoon typechecker). It means you tried to pound a square peg into a round hole. What was the peg and what was the hole? Hoon doesn't tell you by default, because moral fiber, and also because in too many cases trivial errors lead to large intimidating dumps. However, you can use the `~!` rune ([**sigzap**](https://docs.urbit.org/rune/sig#sigzap)) to print the type of any hoon in your stack trace. For instance, you wrote `(foo bar)` and got a `nest-fail`. Change your code to be: ```hoon ~! bar ~! +6.foo (foo bar) ``` You'll get the same `nest-fail`, but this will show the type of `bar`, then the type of the sample of the `foo` gate. ### `find.foo` A `find.foo` error means limb `foo` wasn't found in the subject. In other words, "undeclared variable". The most common subspecies of `find` error is `find.$`, meaning the empty name `$` was not found. This often happens when you use a reference that does not produce a gate/mold, as a gate/mold. For instance, `(foo bar)` will give `find.$` if `foo` is not actually a function. ### `mint-vain` and `mint-lost` These are errors caused by type inference in pattern matching. `mint-vain` means this hoon is never executed. `mint-lost` means there's a case in a `?-` ([**wuthep**](https://docs.urbit.org/rune/wut#wuthep)) that isn't handled. ## Runtime crashes If your code crashes at runtime or overflows the stack, you'll see a stack trace that looks just like the trace above. Don't confuse runtime crashes with compilation errors, though. If your code goes into an infinite loop, kill it with `Ctrl+C` (you'll need to be developing on the local console; otherwise, the infinite loop will time out either too slowly or too fast). The stack trace will show what your code was doing when interrupted. The counterpart of `~!` for runtime crashes is `~|` ([**sigbar**](https://docs.urbit.org/rune/sig#sigbar)): ```hoon ~| foo (foo bar) ``` If `(foo bar)` crashes, the value of `foo` is printed in the stack trace. Otherwise, the `~|` has no effect. ## Debugging printfs The worst possibility, of course, is that your code runs but does the wrong thing. This is relatively unusual in a typed functional language, but it still happens. `~&` ([**sigpam**](https://docs.urbit.org/rune/sig#sigpam)) is Hoon's debugging printf. This pretty-prints its argument: ```hoon ~& foo (foo bar) ``` will always print `foo` every time it executes. A variant is `~?` ([**sigwut**](https://docs.urbit.org/rune/sig#sigwut)), which prints only if a condition is true: ```hoon ~? =(37 (lent foo)) foo (foo bar) ``` For now, you need to be on the local console to see these debug printfs (which are implemented by interpreter hints). This is a bug and, like all bugs, will be fixed at some point.