Node Provider Troubleshooting
Index of the troubleshooting guides node providers reach for first — deployment errors, unhealthy nodes, networking, and failed NNS proposals — plus how to read a node's identity from its console.
This page is the entry point for node-provider troubleshooting. Start here when something is wrong with a node, an onboarding, a network path, or an NNS proposal. The bulk of the procedure detail lives in the four subordinate guides below.
Specific troubleshooting guides
- Troubleshooting node deployment errors — for failures during initial deployment of IC-OS onto a node machine.
- Troubleshooting unhealthy nodes — for nodes that have been successfully deployed but are no longer in a healthy state.
- Troubleshooting networking issues — for IPv6 reachability, IPv4/domain registration, and ISP-side problems.
- Troubleshooting failed NNS proposals — for proposals that fail to validate or adopt.
Getting the node ID from a node
Most diagnostic conversations start with a node's principal (its node ID). To read it directly from the machine:
- Connect a console to the node — either a physical crash cart or the BMC virtual console.
- The node ID prints to the screen on a fresh boot, and again every ten minutes thereafter. Wait for the next print or reboot the node to force one.
- If the node never prints a principal, treat it as a deployment problem — consult the Troubleshooting node deployment errors guide.
[!TIP] Have the node ID ready before you post in the Matrix channel or file a bug report. It is the first thing anyone helping you will ask for.
Node Provider Matrix channel
After consulting the relevant guide, take the question to the Node Provider Matrix channel. Other providers have likely seen the same issue, and DFINITY engineers monitor the channel for incident patterns.
When asking:
- Quote the node ID.
- Quote the exact error or symptom — log lines, console output, proposal IDs.
- Say what you have already tried.
Related
- Node Provider Documentation — the role overview.
- Node Provider Maintenance Guide — the wider operational handbook.
- Troubleshooting Failed NNS Proposals — for governance-side failures.
- Manual Node Recovery Guide — when troubleshooting escalates into a coordinated recovery.