git.iko.soy/urbit.org
on 705ca06 help sign in
urbit.org/tutorials/ship-troubleshooting.md
189 lines 11 kB history raw
1+++
2title = "Ship Troubleshooting"
3weight = 8
4template = "doc.html"
5aliases = ["docs/using/ship-troubleshooting/"]
6+++
8Urbit is still in the development stage, so there's a chance that your ship won't start properly, or will stop working properly when you're running it. That's ok! This document is intended to help you in such an event.
10## Table of Contents
12- [Best practices](#best-practices)
13- [Operation issues](#operation-issues)
14- [Connectivity issues](#connectivity-issues)
15- [Booting issues](#booting-issues)
16- [Crashing issues](#crashing-issues)
18## Best Practices {#best-practices}
20An ounce of prevention is worth a pound of cure, so let's first go over some best practices to keep your ship in working order.
22### Only boot with your keyfile once
24Once your ship is booted with your keyfile, you should never use that same keyfile again. If you do boot with the same keyfile twice, any other ship on the network that your ship has communicated with will not be able to talk to your ship.
26If you accidentally booted with the same keyfile twice, the only remedy is performing a [personal breach](#personal-breach), which is explained in the next section.
28### Do not delete your pier
30Urbit is stateful, meaning that it needs to hold onto all your data. If you delete your pier and start your ship again, you won't be able to talk to any ship you've talked to before. The only solution to this is performing a [personal breach](#personal-breach)
32### Keep track of the directory that you put your ship in
34When you first start your ship, you should make sure you put it a place where you can find it again and where it won't get accidentally deleted. Remember that you must perform `|mount %` in your ship's Dojo to make your ship visible as a directory in the Unix file system.
36### Avoid killing the urbit process directly
38The best way to end an urbit process is to use `ctrl-d` from the Dojo. Unix methods to kill the process, such as with `ctrl-z` or with the `kill` Bash command, or simply closing the window, should only be used if `ctrl-d` does not work.
40### Keep up-to-date builds
42Check for latest Urbit version at https://github.com/urbit/urbit/releases. If you're behind, update using [this guide](@using/install.md).
44### `|hi` your star to see if you're connected
46Find out who your star is by running `(sein:title our now our)` in the Dojo. Then, run `|hi ~star`, where `~star` is the star's name, and if things are working properly, you should get the message `hi ~star successful`. It could also be helpful to use `|hi` to check connectivity with `~zod` or another planet that you're in a Chat channel with.
48### Turn your ship off and on again
50Use `ctrl-d` to gracefully exit your ship, and then start it again. This can solve many issues.
52### Use the `|knob` command to customize your error messages
54Error messages can be by overwhelming, so the `|knob` command is intended to remedy this. It's used to silence errors that aren't important.
56The command takes two arguments, and comes in the form of `|knob %error-tag %level`.
58`%error-tag` is the name of the error in question. It's usually printed at the top of the stack trace, such as in `crud: %hole event failed` -- `%hole` here is an example of an error tag.
60`%level` determines how much you will see of errors with your chosen `%error-tag`. There are three levels:
62- `%hush`: no output.
63- `%soft`: one line of output, just containing the error tag.
64- `%loud`: full output.
66So for example, to silence all Ames packet-related errors, try `|knob %hole %hush`.
68### Perform a personal breach. {#personal-breach}
70A personal breach is when a ship tells all the other ships that have communicated with it to treat it as though the ship was just started for the first time again, since everyone on the network has forgotten about it.
72Personal breaches often fix connectivity issues, but should only be used as a last resort. To find out how to perform a personal breach, check out our [Guide to Breaches](../guide-to-breaches). Before taking such a drastic measure, try other methods in this guide. You can also ask for help on `~/~dopzod/urbit-help`, or, failing that, in the `#ship-starting-support` channel in our [Discord server](https://discord.gg/n9xhMdz).
74## Operation Issues {#operation-issues}
76### My urbit is very slow
78Run `|wash-gall`. This clears caches in Gall, and may result in steep performance improvements.
80### My urbit is frozen
82Sometimes this happens if you're processing a very large event, or if you're in an infinite loop, or for a variety of other reasons.
84Before doing anything, try waiting for a minute: an event might finish processing. If it doesn't clear up, then use the Unix kill-command, `ctrl-z`, to end your ship's process. Then restart your ship.
86### When I try to type into the Dojo, it prints `dy-noprompt`
88This happens when your Dojo is waiting on a request, such as an HTTP request. You can fix it simply by typing `backspace` or (`delete` on Mac).
90### My ship doesn't recognize file changes that I make in my pier
92Since version `0.8.0`, changes no longer automatically sync between the Unix side (your pier) and your ship. To sync your file changes, you must run `|commit %desk` in your Dojo, where `%desk` is the desk you'd like to sync.
94## Connectivity Issues {#connectivity-issues}
96### I can't communicate with anyone
98You may have booted a ship with your keyfile twice in the same era. To fix this, you must perform a [personal breach](#personal-breach).
100### I keep getting an `ames` error stack-trace
102You may see a message like this one: `/~zod/home/~2019.7.22..18.55.46..83a3/sys/vane/ames:<[line column].[line column]>`. This is a clay path to a Hoon file, pointing to the line and column where an expression crashed. This kind of error might be accompanied by a `crud` message.
104This means that another ship is sending invalid packets to you. This could be because one of the ships has not updated the other ship's "life number", which is the number that starts at one and increments every time that ship performs a personal breach.
106This can happen if they have the wrong keys of yours, or if you have the wrong keys of theirs. You can figure out who has the wrong keys by running this scry command in your dojo: `.^(* %j /=life=/shipname)`, where shipname is the other ship's name. Save that information. Then, go to the [Azimuth contract on Etherscan](https://etherscan.io/address/0x223c067f8cf28ae173ee5cafea60ca44c335fecb#readContract), scroll down to `32. points`, and put in the hexadecimal representation of the other ship's `@p`. You can find the hexadecimal representation by running ...
108```
109`@ux`~sampel-palnet
110```
112... in the Dojo, where `~sampel-palnet` is the other ship's name. Then, compare it to the scry information that you saved. If that information matches up, it means that the other ship is the problem. If it **doesn't** match up, your ship has wrong information about the other ship. If you have such wrong information, you can fix this by running:
114```
115:azimuth-tracker|listen ~ %app %azimuth-tracker
116```
118The last line above syncs from an Ethereum node for _all_ ships on the network. If you only wanted to sync with certain ships, run:
120```
121:azimuth-tracker|listen ~[~sampel-palnet ~zod ~marzod] %app %azimuth-tracker
122```
124`~sampel-palnet ~zod ~marzod` are example ship-names; replace these with any number of desired ships-names.
126The above commands work if you have the wrong keys of other ships. If other ships have wrong keys of _yours_, you need to somehow ask them to to run such a command.
128### I can talk to some ships, but I can't talk to my sponsor and some other ships
130This is the result of deleting your pier and starting your ship again. To fix this, you must perform a [personal breach](#personal-breach).
132## Booting Issues {#booting-issues}
134### My ship won't boot and gets a `terminals database is inaccessible` message
136This happens when you try to run the Urbit binary through your `$PATH`. When running the command, you need to be explicit and specify the actual path to it in the filesystem. This is a side-effect of the way we build the release binaries, which will be fixed.
138### My ship booted for the first time, but it turned into a comet instead of my planet or star
140You may have used the wrong arguments when booting your ship for the first time. Delete this comet and try again.
142### My development ship ("fakezod") gets a `boot: malformed` failure
144This means that you gave your development ship an invalid `@p`. So, you will get this error if you write, for example, `urbit -F zodzod` instead of `urbit -F zod`.
146## Crashing Issues {#crashing-issues}
148### I got a `bail` error and my ship crashed
150Try bringing it back up; it will often start working just fine again.
152However, if you get a `bail` error again, you should perform a [personal breach](#personal-breach).
154#### Making a GitHub issue out of your `bail`
156You can get help with you problem by creating an issue at [github.com/urbit/urbit](https://github.com/urbit/urbit/issues). But to make a good issue, you need to include some information.
158When your urbit crashes with a `bail`, you'll probably get a core dump, which is a file that contains the program state of your urbit when it crashed. On Mac, core dumps can be found in `/cores`. On Linux, cores can often be found in `/var/crash`, or the home directory.
160Navigate to the folder containing your core dumps. Find the most recent core dump by looking at the dates after you run `ls -l`. Then `lldb -c <corename>`. Once that loads, you'll be at an `(lldb)` prompt; type `bt` at this prompt. This will create a stack trace that looks like this:
162```
163(lldb) bt
164* thread #1, stop reason = signal SIGSTOP
165 * frame #0: 0x000000010583d871 urbit`_box_free + 17
166 frame #1: 0x0000000105845ee6 urbit`u3j_boot + 182
167 frame #2: 0x000000010584d1f9 urbit`u3m_boot + 89
168 frame #3: 0x000000010583d15d urbit`main + 2765
169 frame #4: 0x00007fff75cb83d5 libdyld.dylib`start + 1
170(lldb)
171```
173Copy this stack trace and include it in your GitHub issue.
175### My ship crashed with a `bail: meme` error.
1771. Make sure you are running version to `0.8.2` if you are not already on it.
1792. Restart your ship. If you don't crash again, everything may be fine. If you **do** crash again, then you should perform a [personal breach](#personal-breach).
181### My ship crashed with a `bail: oops` error
183Restart your ship. These issues often just go away on their own. If this error repeats after restart two or more times, post the messages in an issue at [github.com/urbit/urbit](https://github.com/urbit/urbit/issues).
185This same error might also appear with a message like `Assertion '0'`.
187### My ship crashed with an `pier: work error` error
189This means that the Urbit worker process has shut down for one reason or another. Just restart your ship; this is not a notable or reportable error.