docs: basic troubleshooting page (#111)

MystenLabs · Aug 22, 2024 · abaf0e1 · abaf0e1
1 parent b97995e
commit abaf0e1
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 5 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -36,6 +36,7 @@
   - [Using the client CLI](./usage/client-cli.md)
   - [Using the client JSON API](./usage/json-api.md)
   - [Using the client HTTP API](./usage/web-api.md)
+- [Troubleshooting](./usage/troubleshooting.md)
 - [Examples](./usage/examples.md)
 
 # Walrus Sites

diff --git a/docs/usage/client-cli.md b/docs/usage/client-cli.md
@@ -102,8 +102,3 @@ Use the `--config` option to specify a custom path to the
 The `--wallet <WALLET>` argument may be used to specify a non-standard Sui wallet configuration
 file. And a `--gas-budget <GAS_BUDGET>` argument may be used to change the maximum amount of Sui (in
 MIST) that the command is allowed to use.
-
-## Troubleshooting
-
-If you get an error like "the specified Walrus system object does not exist", make sure your wallet
-is set up for Sui **Testnet** and you use the latest [configuration](./setup.md#configuration).
diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md
@@ -0,0 +1,29 @@
+# Troubleshooting
+
+```admonish tip title="Debug logging"
+You can enable debug logging for Walrus by setting the environment variable `RUST_LOG=walrus=debug`.
+```
+
+## Latest binary
+
+Before undertaking any other steps, make sure you have the [latest `walrus`
+binary](./setup.md#installation). If you have multiple versions in different locations, find the
+the binary that will actually be used with `which walrus`.
+
+## Latest Walrus configuration
+
+The Walrus Devnet and Testnet are wiped periodically and require updating to the latest binary and
+configuration. If you get an error like "could not retrieve enough confirmations to certify the
+blob", you are probably using an outdated configuration pointing to an inactive Walrus system. In
+this case, update your configuration file with the latest [configuration](./setup.md#configuration)
+and make sure the CLI uses the intended configuration.
+
+```admonish tip
+The `walrus` client binary prints information about the used configuration when starting execution,
+including the path to the Walrus configuration file and the Sui wallet.
+```
+
+## Correct Sui network configuration
+
+If you get an error like "the specified Walrus system object does not exist", make sure your wallet
+is set up for Sui **Testnet** and you use the latest [configuration](./setup.md#configuration).