---
title: Node Provider Troubleshooting
slug: node-provider-troubleshooting
description: 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.
tags:
  - node-provider
  - troubleshooting
  - runbook
  - operations
date: 2026-05-04
related:
  - node-provider-documentation
  - node-provider-maintenance
  - troubleshooting-failed-nns-proposals
  - manual-node-recovery
---

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](/wiki/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:

1. Connect a console to the node — either a physical crash cart or
   the BMC virtual console.
2. 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.
3. 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](/wiki/node-provider-documentation/) — the role overview.
- [Node Provider Maintenance Guide](/wiki/node-provider-maintenance/) — the wider operational handbook.
- [Troubleshooting Failed NNS Proposals](/wiki/troubleshooting-failed-nns-proposals/) — for governance-side failures.
- [Manual Node Recovery Guide](/wiki/manual-node-recovery/) — when troubleshooting escalates into a coordinated recovery.