Polykey-CLI Troubleshooting Errors/Bugs

[CryptoTotalWar]

Context

As part of the Docs 1.0 , a dedicated docs section for common known errors and how to do proper debugging and verification.

Requirements

• Evaluate if better to have 1 page dedicated to debugging across all aspects of Polykey-CLI operations
• Add further detail to the step-by-step debuggingprocess info on this ticket to spec out ticket.

Description

Context

To facilitate Polykey users in troubleshooting, this documentation will outline a structured approach for diagnosing and resolving common errors related to network connectivity and cryptolinks.

Step-by-Step Debugging Process

Step 1: Verify Network Connections

Begin by confirming that all nodes are actively connected to the Polykey network. Execute:

polykey nodes connections

This will display all active nodes, including the network's seed nodes. Absence of a user's node may suggest that Polykey is not running or the presence of a restrictive NAT, like a symmetric NAT. For advanced users, specific network configurations may resolve this, whereas others might need to simply switch to usage of PK on less restrictive networks.

To check the connectivity status for a specific node ID:

polykey nodes ping

Step 2: Investigate Multiple Cryptolinks

If network connectivity is intact, inspect for the presence of multiple cryptolinks, which may affect discovery. Detail how users can inspect their cryptolinks and proceed if multiples are detected. Include guidance on starting a new Polykey node when necessary.

Tasks

• 1. Designate a new section within the documentation specifically for debugging procedures, clearly delineating each troubleshooting step.
• 2. Compose the documentation section with precise instructions for verifying node connections, supplemented with command usage examples and anticipated results.
• 3. Describe the process for managing cryptolinks, the complications they may cause, and strategies for resolution.
• 4. Provide references for users to learn about NAT types, including how to ascertain their own NAT type.
• 5. Detail troubleshooting measures for users encountering restrictive NATs, offering alternative networking solutions.
• 6. Ensure the documentation is comprehensive and user-friendly, accommodating the varying levels of user expertise.

[linear]

PRO-87 Create Documentation for Debugging Common Errors