Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

How to Read Signer Logs

There are a lot of different messages you can get in the logs when running a signer. Getting a good grasp on what some of these logs mean can help you troubleshoot effectively and determine if your signer is running successfully or not.

There are three types of log messages you should be aware of:

  • Successful

  • Informational

  • Errors

Successful log messages indicate that you are on track and everything is working as expected. However, there are various success stages depending on several factors including your staking status and the timing of the current reward cycle.

There are also several informational/warning logs that you don't necessarily need to take action on, but they provide useful context about the network or the signer.

Finally, error logs indicate something has gone wrong and you need to take action.

Below are some common log messages you might see, what they mean, and what action (if any) you should take. All examples are from stacks-signer 4.0.4 unless noted.

Successful / informational / error categories — general guidance:

  • Successful: nothing to do unless the message indicates a different stage of operation that requires action (e.g., registration needed).

  • Informational: often safe to ignore, but useful for context.

  • Errors: require investigation and remediation.

Eligible for rewards vs. in the signing set

Two different conditions decide what your signer does in a reward cycle:

  • Eligible for rewards: at least 50,000 STX is delegated to your signer for the cycle. The signer is on PoX-5's per-cycle signer list and its stakers earn rewards. Bond rewards don't depend on this threshold.

  • In the signing set: when the node builds the cycle's signer set from that list, your signer gets a weight of at least 1. Only signers in the signing set sign blocks.

A signer can be eligible for rewards without being in the signing set. See How much stake gets a signer into the signing set.

Successful

Signer started

The signer prints this once at startup. It goes to stdout rather than through the logger, so it has no log level or source location:

Registered for the next cycle

During the prepare phase before a new reward cycle, the signer checks whether it is in that cycle's signing set. If it is, you see:

Action: none.

Signing blocks

When a miner proposes a block, the signer evaluates it and broadcasts its response:

Accepted(BlockAccepted { ... }) means your signer approved the block. Action: none.

Two cycles side by side

After registering for the next cycle, the signer runs one instance per cycle until the switchover. Both receive the same Bitcoin blocks:

The current cycle's instance keeps signing; the next cycle's instance takes over when that cycle starts. Action: none.

Not in the signing set

Signer not registered for a cycle

If your signer is not in a cycle's signing set, it logs this once when it checks the cycle (during the prepare phase before that cycle starts, or after a restart):

After that, the line you see on every Bitcoin block is:

Look for registered_for_current: false and registered_for_next: false. The signer process is running correctly, but it will not sign in this cycle.

The example above is from a mainnet signer with about 50,000 STX delegated. It was in the signing set in cycle 141 and has not been since cycle 142, while its stake stayed locked and kept earning rewards: it is eligible for rewards but not in the signing set.

Action:

  • Confirm your signer-manager holds a grant for this signer key: the signer-manager calls grant-signer-key with your signature, then register-signer. See Deploy a Signer Manager Contract and Key and Address Rotation.

  • Confirm stake is routed through your signer-manager for the cycle, through stake, stake-update, register-for-bond or update-bond-registration. See Staking STX.

  • Compare the stake delegated to your signer with the cycle's pox_ustx_threshold (below). If it is lower, attract more stake to sign reliably.

How much stake gets a signer into the signing set

50,000 STX makes a signer eligible for rewards. Getting into the signing set depends on how much STX is staked in total. For each cycle, the node computes:

  1. pox_ustx_threshold = ceil(total STX delegated to signers that are eligible for rewards / reward slots). There are 4,000 reward slots on mainnet and 1,600 on the public testnet (900-block cycles with a 100-block prepare phase).

  2. Each signer's weight is floor(stake / pox_ustx_threshold).

  3. Slots left over after step 2 go one each to the signers with the largest remainders.

  4. Signers that end with weight 0 are left out of the signing set.

Stake at or above pox_ustx_threshold guarantees a place in the signing set. Below it, a signer gets in only if it wins a leftover slot, which depends on every other signer's stake.

Mainnet, cycle 144: about 448.3 million STX was delegated to eligible signers, so pox_ustx_threshold was 112,082,393,974 uSTX, about 112,083 STX. A signer needed at least that much delegated to be sure of a place in the signing set. The threshold rises as total stake rises (it was about 98,112 STX in cycle 141), so leave a margin and check it each cycle.

To read the threshold and the signing set for a cycle, query your node's RPC endpoint:

In the response, stacker_set.pox_ustx_threshold is the threshold in uSTX, and stacker_set.signers lists the signing set. Your signer is in the set if its signing_key appears there with a weight of 1 or more. Replace localhost:20443 with your node's RPC address.

Source: stackslib/src/chainstate/nakamoto/signer_set.rs in stacks-core 4.0.4.

Informational

Peer not connecting

If you see a message about a peer not connecting, for example (from an earlier stacks-node release):

This means your node attempted to connect to another node on the network but was unable to. This can happen for many reasons (network connectivity, remote node offline, NAT/firewall, etc.).

Action:

  • Usually not a cause for concern and does not impact whether your signer is running correctly.

  • If you see many such messages or persistent connectivity issues, investigate network connectivity, firewall/NAT rules, or peer configuration.

Finding these lines in your logs

Filter the signer's output for the messages on this page. How you read the output depends on how you run the signer:

Signer spawned successfully goes to stdout, while the logger writes to stderr. Keep 2>&1 (or capture both streams) so the startup line isn't lost.

Last updated

Was this helpful?