besu-eth · alexandratran · Sep 15, 2022 · Sep 14, 2022 · Sep 14, 2022 · Sep 14, 2022
diff --git a/docs/global/how-to/troubleshoot/troubleshooting.md b/docs/global/how-to/troubleshoot/troubleshooting.md
diff --git a/docs/private-networks/get-started/install/run-docker-image.md b/docs/private-networks/get-started/install/run-docker-image.md
@@ -14,9 +14,9 @@ Use this Docker image to run a single Besu node without installing Besu.
 
 * MacOS or Linux
 
-!!! important
+    !!! important
 
-    The Docker image does not run on Windows.
+        The Docker image doesn't run on Windows.
 
 ## Expose ports
 
@@ -70,7 +70,7 @@ docker run -p <localportJSON-RPC>:8545 -p <localportWS>:8546 -p <localportP2P>:3
     [`--nat-method`](../../../public-networks/how-to/connect/specify-nat.md) to `NONE` or `UPNP`.
 
 You can specify
-[Besu environment variables](../../../public-networks/reference/cli/options.md#besu-environment-variables) with the
+[Besu environment variables](../../../public-networks/reference/cli/options.md#specify-options) with the
 Docker image instead of the command line options.
 
 !!! example
@@ -79,6 +79,21 @@ Docker image instead of the command line options.
     docker run -p 30303:30303 -p 8545:8545 -e BESU_RPC_HTTP_ENABLED=true -e BESU_NETWORK=goerli hyperledger/besu:latest
     ```
 
+??? caution "Unsupported address type exception"
+
+    When running Besu from a Docker image, you might get the following exception:
+
+    ```bash
+    Unsupported address type exception when connecting to peer {}, this is likely due to ipv6 not being enabled at runtime.
+    ```
+
+    This happens when the IPv6 support in Docker is disabled while connecting to an IPv6 peer,
+    preventing outbound communication.
+    IPv6 is disabled by default in Docker.
+
+    [Enable IPv6 support in Docker](https://docs.docker.com/config/daemon/ipv6/) to allow outbound
+    IPv6 traffic and allow connection with IPv6 peers.
+
 ### Run a node for testing
 
 To run a node that mines blocks at a rate suitable for testing purposes with WebSocket enabled:

diff --git a/docs/private-networks/how-to/configure/consensus/ibft.md b/docs/private-networks/how-to/configure/consensus/ibft.md
@@ -71,15 +71,36 @@ The properties specific to IBFT 2.0 are:
 
 !!! caution
 
-    We do not recommend changing `epochlength` in a running network. Changing the `epochlength`
+    We don't recommend changing `epochlength` in a running network. Changing the `epochlength`
     after genesis can result in illegal blocks.
 
+??? caution "Invalid block header error"
+
+    When adding a new node, if a `TimeStampMoreRecentThanParent | Invalid block header` error occurs,
+    the genesis file of the new node specifies a higher `blockperiodseconds` than the imported chain.
+    The imported chain makes new blocks faster than the genesis file allows and Besu rejects them
+    with this error.
+    This error most often occurs when importing chains from older versions of Besu.
+
+    Decrease the `blockperiodseconds` in the new IBFT 2.0 genesis file to a lower value that
+    satisfies the block header validation.
+
+    !!! example
+
+        If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp
+        1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`,
+        decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain.
+
+    After you update the new genesis file, if the imported chain has a `blockperiodseconds` value
+    set lower than you prefer, you can adjust it by [configuring the block time on an existing IBFT
+    2.0 network](#configure-block-time-on-an-existing-network).
+
 The properties with specific values in the IBFT 2.0 genesis files are:
 
 * `nonce` - `0x0`
 * `difficulty` - `0x1`
 * `mixHash` - `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` for Istanbul
-  block identification.
+  block identification
 
 To start a node on an IBFT 2.0 private network, use the
 [`--genesis-file`](../../../../public-networks/reference/cli/options.md#genesis-file) option to specify the custom

diff --git a/docs/private-networks/how-to/configure/consensus/qbft.md b/docs/private-networks/how-to/configure/consensus/qbft.md
@@ -155,14 +155,35 @@ The QBFT properties are:
 
 !!! caution
 
-    We do not recommend changing `epochlength` in a running network. Changing the `epochlength`
+    We don't recommend changing `epochlength` in a running network. Changing the `epochlength`
     after genesis can result in illegal blocks.
 
+??? caution "Invalid block header error"
+
+    When adding a new node, if a `TimeStampMoreRecentThanParent | Invalid block header` error occurs,
+    the genesis file of the new node specifies a higher `blockperiodseconds` than the imported chain.
+    The imported chain makes new blocks faster than the genesis file allows and Besu rejects them
+    with this error.
+    This error most often occurs when importing chains from older versions of Besu.
+
+    Decrease the `blockperiodseconds` in the new QBFT genesis file to a lower value that satisfies
+    the block header validation.
+
+    !!! example
+
+        If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp
+        1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`,
+        decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain.
+
+    After you update the new genesis file, if the imported chain has a `blockperiodseconds` value
+    set lower than you prefer, you can adjust it by [configuring the block time on an existing QBFT
+    network](#configure-block-time-on-an-existing-network).
+
 The properties with specific values in the QBFT genesis files are:
 
 * `difficulty` - `0x1`
 * `mixHash` - `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` for Istanbul
-  block identification.
+  block identification
 
 To start a node on a QBFT private network, use the
 [`--genesis-file`](../../../../public-networks/reference/cli/options.md#genesis-file) option to specify the custom

diff --git a/docs/private-networks/reference/cli/options.md b/docs/private-networks/reference/cli/options.md
@@ -42,6 +42,12 @@ If using Bash or Z shell, you can view option suggestions by entering `--` and p
 besu --Tab+Tab
 ```
 
+!!! caution
+
+    Characters such as smart quotes and long (em) hyphens don't work in Besu command line options.
+    Ensure quotes aren't automatically converted to smart quotes, or double hyphens combined into em
+    hyphens.
+
 ## Options
 
 ### `permissions-accounts-config-file`

diff --git a/docs/public-networks/get-started/install/run-docker-image.md b/docs/public-networks/get-started/install/run-docker-image.md
@@ -14,9 +14,9 @@ Use this Docker image to run a single Besu node without installing Besu.
 
 * MacOS or Linux
 
-!!! important
+    !!! important
 
-    The Docker image does not run on Windows.
+        The Docker image doesn't run on Windows.
 
 ## Default node for Mainnet
 
@@ -86,7 +86,7 @@ docker run -p <localportJSON-RPC>:8545 -p <localportWS>:8546 -p <localportP2P>:3
     [`--nat-method`](../../how-to/connect/specify-nat.md) to `NONE` or `UPNP`.
 
 You can specify
-[Besu environment variables](../../reference/cli/options.md#besu-environment-variables) with the
+[Besu environment variables](../../reference/cli/options.md#specify-options) with the
 Docker image instead of the command line options.
 
 !!! example
@@ -95,6 +95,21 @@ Docker image instead of the command line options.
     docker run -p 30303:30303 -p 8545:8545 -e BESU_RPC_HTTP_ENABLED=true -e BESU_NETWORK=goerli hyperledger/besu:latest
     ```
 
+??? caution "Unsupported address type exception"
+
+    When running Besu from a Docker image, you might get the following exception:
+
+    ```bash
+    Unsupported address type exception when connecting to peer {}, this is likely due to ipv6 not being enabled at runtime.
+    ```
+
+    This happens when the IPv6 support in Docker is disabled while connecting to an IPv6 peer,
+    preventing outbound communication.
+    IPv6 is disabled by default in Docker.
+
+    [Enable IPv6 support in Docker](https://docs.docker.com/config/daemon/ipv6/) to allow outbound
+    IPv6 traffic and allow connection with IPv6 peers.
+
 ### Run a node for testing
 
 To run a node that mines blocks at a rate suitable for testing purposes with WebSocket enabled:

diff --git a/docs/public-networks/how-to/connect/manage-peers.md b/docs/public-networks/how-to/connect/manage-peers.md
@@ -100,3 +100,15 @@ To disable P2P discovery, set the
 With discovery disabled, peers can't open connections with the node unless they were previously discovered or manually
 peered (for example, using [`admin_addPeer`](../../reference/api/index.md#admin_addpeer)).
 [Static nodes](static-nodes.md) can also open connections.
+
+## Troubleshoot
+
+If your nodes fail to connect, ensure the
+[required ports are open](configure-ports.md).
+
+If your nodes are running in AWS, check you have appropriate `SecurityGroups` to allow access to
+the required ports.
+
+Check that the [enode URLs](../../concepts/node-keys.md#enode-url) specified for
+[bootnodes](../../../private-networks/how-to/configure/bootnodes.md) or
+[static nodes](static-nodes.md) match the enode URLs displayed when starting the remote nodes.