§ Wiki · Wiki entry

Troubleshooting Failed NNS Proposals

What to do when a Network Nervous System proposal you submitted as a node provider fails to validate or fails to adopt.

·May 4, 2026·3 min read

[!NOTE] The upstream wiki entry for this runbook has been removed and now redirects to a Cloudflare-protected page on DFINITY's learning portal at learn.internetcomputer.org, which was not accessible at the time of this migration. The guidance below reflects general practice and may diverge from the current authoritative version. Cross-check the Proposals article on the learning portal, or ask in the Node Provider Matrix channel, before following any specific step.

Many node-provider actions — onboarding a machine, retiring one, updating an IPv4 address, changing a principal — are submitted as proposals to the Network Nervous System (NNS). This page collects the common reasons those proposals fail and what to check before resubmitting.

Before you resubmit

A proposal that did not adopt is not always a bug — it may simply have been rejected. Distinguish three cases:

  1. The proposal failed to validate — the proposal payload was malformed and the NNS rejected it without a vote. Re-prepare and resubmit.
  2. The proposal was voted down — neurons rejected the substance of the proposal. Talk to the community before resubmitting.
  3. The proposal was adopted but the action did not take effect — rare; treat this as an incident and surface it on the Node Provider Matrix channel with the proposal ID.

Common validation failures

Proposals that fail at validation usually do so for one of these reasons:

  • Wrong neuron ID or principal. Double-check that the controller signing the proposal is the same principal the NNS expects for your node-provider record.
  • Stale registry data. The state the proposal references — node ID, data-center key, IPv4 / IPv6 entry — has already changed. Re-pull the current registry state and rebuild the proposal.
  • Mistyped fields. Hex node IDs, IPv6 addresses, and domain names are exact matches. A single character off and validation fails.
  • Missing reward configuration. Reward-related proposals require the data-center and reward-rate records to exist already.

For each, fix the underlying input, regenerate the proposal payload, and resubmit.

Common reasons proposals get voted down

If your proposal validated but did not adopt:

  • Missing forum context. New regions, new data centers, and reward-rate changes need a forum discussion ahead of the proposal. Without that thread, neurons typically vote no.
  • Decentralization concerns. Proposals that would concentrate the network in a single jurisdiction, provider, or hardware supplier are routinely rejected.
  • Insufficient time on the floor. Some proposals need a week or more for community review before the votes accumulate. Check the voting window before assuming failure.

Where to verify state

  • Proposal status: look up the proposal ID on dashboard.internetcomputer.org.
  • Registry state: the dashboard exposes node, data-center, and node-provider records.
  • Forum context: searches at forum.dfinity.org typically surface the discussion thread for any non-trivial governance change.

When to ask for help

Surface the issue in the Node Provider Matrix channel if:

  • Validation keeps failing for a reason you cannot identify.
  • A proposal adopted but the on-chain state does not reflect it.
  • You are unsure whether a forum thread is needed before resubmitting.

Always quote the proposal ID and the exact error text.

Related