Hoon, Urbit Errors and what they mean

See also Hoon Errors on urbit.org

Most of this is transcribed from the Assembly 2021 handout.

Common error messages

  • mint errors
    • mint-nice - failure to cast. you failed to pass/conform to a type somewhere
    • mint-vain - hoon never executed; impossible match in ?-, ?+, ?~, ?=. when there is a conditional that has no possible way to reach a branch. A required branch that is missing. or an extra case in a ?- wuthep.
      • make sure all branches are reachable
    • mint-lost - branch can never be reached. missing a case in a ?- wuthep switch
      • make sure all branches are reachable
  • fish-core - attempt to match a core as a mold
    • don’t use a core with ?= pattern matching
  • fish-loop - recursive mold definition “fishing to see whether the value on the right matches the mold on the left”. Say you give a ?= something like ?=((list @) ~[1 2 3 4]), there is a recursive type here, and wuttis doesn’t want to get into looping, so it fails.
    • done’t use mold types like list with ?= pattern matching
  • naked generator - something is generally wrong.
  • generator build failure - probably miscounted rune children
  • nest-fail - a kind of type error. something doesn’t fit into the mold you’re giving it.
  • %generator-build-fail - syntax issues, cannot be a well-formed program
  • mull
    • mull-grow - failure to compile at wet gate callsite. has to do with wet gates and how they nest inside one another.
    • mull-bonk - various pattern matching errors
    • mull-nice - type nesting errors
  • runtime errors / bail - crashed on execution itself.
    • bail:exit - semantic failure
    • bail:evil - bad crypto
    • bail:fail - execution failure
    • bail:foul - assertion of failure
    • bail:meme - out of memory / loom issue
    • bail:need - network block
    • bail:oops - assertion failure
    • bail:time - operation timeout
    • loom:corrupt - memory corruption
    • pier: serf unexpectedly shut down - runtime crash.
  • find. foo - failure to locate limb in subject
    • check the wing (limb search path), make sure limb exists
  • find. $ - failure to call item as gate
    • ensure that the code is calling a gate
  • find-fork - insufficient resolution in typechecker
    • use ?> to assert type before use

Common Bugs

  • Aura mismatches - mint-nice, etc
    • Pass through empty aura before final cast: ^-(@ud ^-(@ 'foo'))
  • Generator issues
    • Check children of each rune to make sure they match
    • Check return types of expressions (or limit with with ?>/^-)
  • Shadowed faces - Variable names (such as json) covered in the subject by another limb name
    • Use ^ to find the n th match or change limb name

Strategies

  • Stack debugging
    • turn on with !:. turn off with !.. The output on a crash returns the stack and current file/line number.
  • “puts/printf”-debugging
    • use ~& freely.
  • Bisection seach
    • stub out limbs you aren’t testing with !!. Target where the issue is.
  • Build it again.
    • like above, remove complicated code and replace with sigpam and zapzap, or hardcode a return value.

Debugging Tools

  • ~ tools
    • ~& emit printed messages as side-effects
    • ~| turns on a tracing message for stack debugging
    • ~_ produce a developer-formatted tracing message
    • ~! print type on compilation failure
  • ! tools
    • !: turn on stack debugging
    • !. turn off stack debugging