Guide · 11 chapters · 27 rules · real finney data
Subnets, miners, validators, consensus and the errors that cost you TAO, in plain words. Every example is a real read from finney, and every problem links to the Preflight rule that catches it
Chapter 01
Subnets are competitions: miners do the work, validators score it, and every tempo the chain pays both in the subnet's own token
Bittensor is a blockchain that pays people to do useful work, such as running AI models, collecting data or renting out GPUs. The work is split into , each one a competition with its own task. On every subnet, do the work and check it and score it. The chain adds up the scores, weighted by how much each validator has, and pays out on a fixed clock called the . Underlined words open a short definition
Every participant has a pair of keys. The is the owner and holds the money, so it should never sit on a server. The is the worker: it is what registers on a subnet and what Preflight diagnoses. Read more in the network overview
Coldkey
the owner, keep it offline
Hotkey
the worker, one per neuron
Chapter 02
A miner pays to register, gets a grace period to be noticed, earns only once validators score it, and is replaced if it earns the least
Every miner goes through the same stages: it pays a to register, sits in while validators find its , earns once they score it, and can be . Hover or tap each stage, or use the arrow keys, to see what tends to go wrong there and which Preflight rule catches it. The numbers are real SN64 reads. See the official mining guide and burn registration for the full detail
Chapter 03
Zero almost always comes down to one of five causes, and the Doctor checks every one of them against a single block
Check these in order, because each one hides the next: an unregistered miner cannot be reached, an unreachable miner cannot be scored, and so on. The findings below are real Doctor output, rendered with the same components as a live diagnosis
preflight doctor <hotkey> --netuid <netuid>No means no validator can score it. It happens more often than you would think: the hotkey registered on another netuid, or lost its seat to , which PF102 catches. The fix is to register, and the Doctor fills the command in with the live cost
Recorded finding, a hotkey with no UID on SN64, block 9,376,731
btcli subnets register --netuid 64 --hotkey 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY --network finneyCosts about 0.0005 TAO right now; the price moves with demand
This hotkey holds no UID on this subnet, so validators cannot score it and it earns nothing. The subnet is full, so registering replaces the lowest emission neuron that is out of immunity
| Evidence | Value | Source |
|---|---|---|
| Hotkey5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY | derived | |
| UIDs in use256 of 256SubtensorModule.MaxAllowedUids | SubtensorModule.MaxAllowedUids | |
| Registration cost now0.0005 TAOSubtensorModule.Burn | SubtensorModule.Burn |
All values read at block 9,376,731
Validators find miners through the address on chain. No address, 127.0.0.1, a LAN address or 0.0.0.0 all mean their queries never arrive. Not every subnet uses axons: on SN64 most earning miners publish none, so the Doctor only raises PF105 where earning miners do
The command PF105 hands you, with your netuid filled in
btcli axon set --netuid <netuid> --ip <public-ip> --port 8091 --network finneyUse the public address validators can reach; the miner process must listen on that port
The most common answer. The miner is registered and may well be reachable, but none of the permitted validators' latest include it. The evidence lists the biggest validators and when each last set weights, so you can tell a quiet subnet from a miner that is being skipped
Recorded finding, UID 0 on SN64, block 9,376,730
Fix
Check that the axon is reachable and that the miner answers the subnet's queries in the format validators expect
Incentive only comes from validators putting weight on a UID. None of the permitted validators' latest weights include this one, so it earns nothing until they do
| Evidence | Value | Source |
|---|---|---|
| Validators weighting this UID0 of 17 | derived | |
| UID 1 (5DU1dv...S7ww)stake 1,385,417 alpha, last set weights 18 blocks (about 4 min) agoSubtensorModule.LastUpdate | SubtensorModule.LastUpdate | |
| UID 252 (5E2LP6...eZ5u)stake 907,925 alpha, last set weights 138 blocks (about 28 min) agoSubtensorModule.LastUpdate | SubtensorModule.LastUpdate | |
| UID 59 (5CS3g6...2xbV)stake 765,922 alpha, last set weights 18 blocks (about 4 min) agoSubtensorModule.LastUpdate | SubtensorModule.LastUpdate | |
| UID 46 (5CAAxT...pQ1C)stake 336,362 alpha, last set weights 3 blocks (about 36 s) agoSubtensorModule.LastUpdate | SubtensorModule.LastUpdate | |
| UID 61 (5GRbxc...CdXc)stake 205,685 alpha, last set weights 20 blocks (about 4 min) agoSubtensorModule.LastUpdate | SubtensorModule.LastUpdate |
All values read at block 9,376,730
Some validators weight it, but together they hold less than of the stake, so Yuma Consensus throws the weight away. Chapter 4 lets you try it with real SN64 stakes
What PF110 tells you to do
Fix
More of the large validators need to score this UID; check it answers their queries
Sometimes the miner is fine and the subnet is not. On SN26 at this block, three of its five validators had stopped setting weights and the owner's burn UID took all of the miner incentive, so a new miner there had nothing to win. Preflight reports these as signals about the subnet, never as verdicts
Recorded finding, SN26, block 9,376,730
Chapter 04
A weight only counts as far as validators holding kappa of the stake agree with it, so one validator alone cannot make a miner earn
Validators do not simply vote a miner up. Each , looks at every weight on a miner and keeps only as much of it as validators holding at least of the stake agree on. Anything above that is clipped. If too little stake weights a miner at all, its consensus weight is zero and so is its incentive, even though some validators scored it
Try it below with the five largest validators on SN64. Switch validators on and off, move kappa, and watch whether the miner's weight survives. This is the exact check behind PF110
Finney subnets typically run 50%. SN64 reads 0.5
Validator stake that weighted the miner
Clipped to zero, the miner earns nothing
Only 36.3% of the stake weighted it, below kappa (50%). Consensus clips the weight to zero, so incentive is 0. This is the case PF110 reports
The real epoch is finer grained: it clips each weight to the highest value that kappa of stake supports, so validators who agree a miner is good but disagree on how good still lose some weight. That partial loss shows up as low , which is what PF111 watches. The full model is in Yuma Consensus
Chapter 05
A validator needs enough stake for a permit, must set weights often enough to stay active and no faster than the rate limit
A validator earns for scoring miners well. To do that it needs stake, a and weights that reach the chain on time, inside the . Most validator problems are one of the checks below failing, and the chain error names which one. See the validating guide and timelock for
Alpha staked to the hotkey, plus discounted TAO
Top stake weight on the subnet, recomputed each epoch
Score miners, then set_weights or commit them
Fresh weights inside the activity cutoff
Steps 3 and 4 repeat for as long as the validator runs, no faster than the rate limit and no slower than the cutoff
Permit
MaxAllowedValidators
64 permits on SN64
Each epoch the top neurons by stake weight get a permit. Without one, weights on other UIDs are refused
NeuronNoValidatorPermit
Stake
StakeThreshold
about 1,000 TAO equivalent on mainnet
The hotkey's stake weight must reach the threshold. The subnet owner's hotkey is exempt
NotEnoughStakeToSetWeights
Version
WeightsVersionKey
0 on SN64, so not enforced
When the owner sets a version key, validators must send at least that version
IncorrectWeightVersionKey
Rate limit
WeightsSetRateLimit
100 blocks on SN64, about 20 min
A validator must wait this many blocks after its last weights before sending new ones
SettingWeightsTooFast
Shape
MinAllowedWeights, MaxWeightsLimit
1 UID and 100% on SN64
Weights must cover enough UIDs and keep each single weight under the cap
WeightVecLengthIsLow, MaxWeightExceeded
SN64 values from its hyperparameters as recorded at block 9,376,750. The stake threshold is from the validating guide
Activity cutoff
5,000 blocks on SN64, about 16.7 h
No error, which is why this one hurts: weights older than the cutoff are silently ignored and earn no dividends
Commit reveal
Off on SN64; up to 10 unrevealed commits per hotkey where it is on
Weights are encrypted to a future drand round and only count once the chain reveals them
Self weighting
Half or more of the weight to its own coldkey
Looks like self mining. A signal, never a verdict
Copier signature
Correlation above 0.98 with last epoch's consensus
Looks like weight copying, which commit reveal exists to stop. A statistical signal only
This validator set weights 18 blocks before the read. The rate limit on SN64 is 100 blocks, so a new call would fail with SettingWeightsTooFast until block 9,376,812. That is information, not a fault: the fix is to wait, and retrying in a tight loop only burns time
Blocks since each permitted validator last set weights, read at block 9,376,730 (the PF108 evidence for UID 82 on SN26), on a log scale. PF305 calls a validator stale after max(2 tempos, rate limit plus a tempo), here 720 blocks or about 2.4 h
Chapter 06
Every failed extrinsic names the pallet and the error that stopped it; the rest is reading the chain state it was checked against
This is a real validator on finney that failed. Every failure names the and the error that stopped it. Here is how to read one, top to bottom, the same way the transaction debugger does
Explorers name an extrinsic by its block and its position in that block. 9376733-28 is the 29th extrinsic in block 9,376,733, since the index starts at 0. Preflight takes that form, a 0x hash from the last 300 blocks, or the error text you were shown
Reference
9376733block-28index
The signer is a validator's , because weights are signed by the hotkey. The call is commit_timelocked_mechanism_weights: on a commit reveal subnet, validators commit weights encrypted until a future round instead of setting them in the open
Call
SubtensorModule.commit_timelocked_mechanism_weights
Each argument is decoded from the raw call. The ones that matter here are the subnet, and the round that tells the chain when it may decrypt the commit
Decoded arguments
The fee is charged first, then the runtime dispatches the call. ExtrinsicFailed carries the module error that stopped it. The fee was 0 TAO, so the only cost was a commit that never landed
Events
TransactionPayment.TransactionFeePaid
Fee paid 0.000000000 TAO
System.ExtrinsicFailed
Failed with SubtensorModule.TooManyUnrevealedCommits
TooManyUnrevealedCommits comes from the official error catalog with its semantic code and the line in subtensor that raises it. The catalog says the limit: 10 unrevealed commits per hotkey on a subnet
Dispatch error
SubtensorModule.TooManyUnrevealedCommits
The debugger rereads the chain at the block before, so the explanation names this hotkey's queue, not a generic limit. Timelocked commits reveal themselves when their drand round arrives, so the answer is to wait, and commit less often. shows the same queue in the Doctor before it fills
Why it failed
Before this block the hotkey already had 10 unrevealed commits queued on the subnet, so the runtime refused another
Wait
Let the queued commits reveal (timelocked commits reveal on their drand round) before committing again
Read from finney at block 9,376,733, runtime 486. Recorded in docs/demo-output/tx-mainnet.json
Chapter 07
The simulator runs your extrinsic against a copy of mainnet, so you see the exact error before you spend a single rao
A failed registration still costs its fee, and the burn can move between your quote and your retry. The simulator answers “would this work right now” without sending anything, by running the chain's own on a or predicting from the same rules. It always says which one it used
Each line is one condition the chain tests, with the value it read at block 9,377,481. Two fail, so the chain would reject the call before it runs and nothing would be spent
preflight sim burned_register --netuid 64 --coldkey <ss58> --hotkey <ss58>Preflight copies mainnet at one block onto your machine and runs your transaction through the chain's own code. You get exactly the answer the chain would give, and then the copy is thrown away, so nothing is ever sent
Preflight reads the live numbers that decide the outcome, such as the burn, your balance and the registration limits, and runs the same checks the chain runs, copied from its source code
The bittensor SDK has client.plan(), which returns fees and effects. It never runs the call, so it said ok to all three of these. Preflight uses it for fee and effect text only, never for the verdict
Fork of finney block 9,376,889. The first call on a new path fetches storage lazily, which is why it can take minutes; requests fall back to the prediction after 20 s while the fork warms
Chapter 08
A subnet costs a TAO lock that doubles after each registration and decays back, and at 128 subnets a new one replaces another
Launching a subnet means paying the , waiting for the network , possibly replacing another subnet, and calling before anyone earns. These are the real numbers from finney at block 9,377,485
At block 9,377,485 the lock cost was 346.366 TAO. With no new registrations it falls about 0.0078 TAO per block, to about 336.9668 TAO at block 9,378,690 and to the 1 TAO floor at block 9,421,762
From docs/demo-output/plan.txt. Each subnet registration doubles the cost for the next one, so on a live chain this line jumps back up every time someone registers, then decays again
Register and start_call
#9,378,690
The first block the 14,400 block rate limit allows. Registering locks the cost and makes you owner; on finney start_call can follow at once
then +361 blocks, 1.2 h
First emissions
#9,379,051
Paid by the first epoch after start_call, within one tempo of 360 blocks
then +431,639 blocks, 60 days
Immunity ends
#9,810,690
From here the subnet can be replaced when a new one registers at the cap
At 128 subnets, a new registration dissolves the subnet with the lowest moving alpha price among those past their immunity. At this block that was SN16 Zero Hour. The planner names it before you pay, along with the exact block the rate limit lifts
# What it costs and when you can registerpreflight plan --network finneybtcli subnets create-cost# After registering, start emissions (owner coldkey only)btcli hparams start --netuid <netuid> --network finneyThat is the guide
Paste a hotkey, a transaction or an error. Preflight reads the chain at one block and tells you which of the problems above you have, with the command that fixes it. Below is reference: every rule, every way to run Preflight, and a glossary
Chapter 09
27 rules, each a small pure function over one block of chain state, grouped by who they are for
Every finding the Doctor returns comes from one of these rules. Each reads a single pinned block, cites the storage item it read, and ships with tests for when it fires and when it does not. Link to any row with its id, like /guide#pf110
27 rules shown
Not registerednot_registered
The hotkey holds no UID on this subnet, so no validator can score it
Recently deregisteredrecently_deregistered
It had a UID and lost it: it was the lowest earner out of immunity when someone registered on a full subnet
In immunityin_immunity
Registered less than ImmunityPeriod blocks ago, so low early rewards are normal and it cannot be pruned yet
Near pruningnear_pruning
Out of immunity and among the lowest emission neurons, so the next registration on a full subnet can remove it
Axon not servedaxon_not_served
No axon address on chain, on a subnet where most earning miners publish one
Axon address unreachableaxon_bad_address
The axon points at a loopback, private or unspecified address that validators cannot reach
Axon did not answeraxon_unreachable
A TCP connection to the advertised axon was refused or timed out. Runs only when you ask for a probe
No validator weightno_validator_weight
No permitted validator's latest weights include this UID, so it earns nothing
Only stale validators score itweights_from_stale_validators_only
Every validator that scores it is past the activity cutoff, and the epoch ignores their weights
Weighted but clippedincentive_zero_but_weighted
Validators weight it, but they hold less than kappa of the stake, so consensus clips it to zero
Low trustlow_trust
Trust is under half the median of earning miners, so validators disagree about it and part of its weight is clipped
Coldkey crowdingduplicate_coldkey_crowding
Five or more UIDs on this subnet share its coldkey, a pattern owners look for. Plenty of honest operators run several
Weights versionversion_mismatch
The subnet requires a minimum weights version key; validators on older code are rejected
No validator permitno_validator_permit
Has stake but no permit, so setting weights on other UIDs fails with NeuronNoValidatorPermit
Weights staleweights_stale
Has not set weights within the activity cutoff, so its weights are ignored, or has missed at least an epoch
Rate limitedrate_limited
Set weights less than WeightsSetRateLimit blocks ago, so a new call fails with SettingWeightsTooFast
Below weights minimum stakebelow_min_stake_for_weights
Stake weight is below StakeThreshold, so setting weights fails with NotEnoughStakeToSetWeights
Commit pending revealcommit_pending_reveal
Committed weights are waiting to be revealed, and they only count once they are
Weight limitsweights_too_few_uids
Its last weights cover fewer than MinAllowedWeights UIDs or put more than MaxWeightsLimit on one
Self weightingself_weighting
Half or more of its weight goes to UIDs under its own coldkey, which looks like self mining
Copier signaturecopier_signature
Its weights track last epoch's consensus almost exactly, which looks like weight copying. A statistical signal only
Registration closedregistration_closed
Registration is switched off, or this block's or this interval's registration slots are used up
Burn spikingburn_spiking
The registration cost is at least twice its recent average, so registering now pays a premium
Emissions not startedemissions_not_started
The owner has not called start_call yet, so nobody on the subnet earns and staking is blocked
Near full burnnear_full_burn
90% or more of miner incentive goes to the owner's burn UID, so there is little left for real miners
Validators staleweights_mostly_stale
More than half of the permitted validators have stopped setting weights, so scores barely move
Owner self miningowner_self_mining
30% or more of miner incentive goes to other hotkeys under the owner's coldkey. Can be bootstrapping on a young subnet
Severity is what each rule is declared with. Some findings come out lower, such as PF108 while a miner is still in immunity
Chapter 10
One engine answers the CLI, the website, the HTTP API, your own Claude, CI and Telegram, with the same JSON
Install once with uv, then ask from any terminal. Add --json for machine output and --fail-on high to fail a script when something is wrong
uv tool install git+https://github.com/Adwaitbytes/preflightpreflight doctor 5EKtvzbEvYZPRJdo42ug7mWrHdt4AurCNMs5CAefuBHfQmhq --netuid 64preflight tx 9376733-28preflight plan BROKEN UID 0 on SN64 earns nothing because no validator has scored itfinney at block 9,377,476, runtime 486 4,451 ms CRITICAL PF108 No validator has scored this UID Validators weighting this UID 0 of 17 UID 1 (5DU1dv...S7ww) stake 1,385,572 alpha, last set weights 163 blocks (about 33 min) ago UID 252 (5E2LP6...eZ5u) stake 908,518 alpha, last set weights 164 blocks (about 33 min) agoChapter 11
Every term on this page in a sentence or two
48 terms