Troubleshooting

The registration banner will not go away

The node cannot find itself in StarRegistry. Check, in this order:

1. The register transaction went through — look it up in a block explorer.
2. The signer address you registered matches the one in the banner, character for character.
3. BLOCKCHAIN_RPC_URL points at the network the contracts are on.
4. Then read the container logs. Timeouts mean the node never reached the RPC.

You do not need to restart after registering. The node watches the chain and picks up its starId by itself.

“No active Control Plane”

Stargate cannot reach any Control Plane over gRPC. The likeliest causes first:

1. A Control Plane is running but has not published an endpoint — that is the Set Endpoint button.
2. The endpoint points at an address that does not answer or a closed port. Check with grpcurl <host>:<port> singula.admin.v1.AdminService/GetHealth.
3. The Control Plane’s signer has run out of ETH.
4. Nothing in the network is answering right now.

In the last case there is nothing to fix on your side. Managing Stars through the chain still works; only the live statistics are missing.

The Control Plane turns the node away

The node’s log shows the Control Plane refusing its registration with registration is not signed by its signer key. At registration a node proves it holds its Star’s signer key, and the node and the Control Plane have to agree on how that proof is built. They do not when one of them runs an older image. Update the node to the current singulanetwork/star:alpha and restart it; the identity is kept.

The node runs but gets no sessions

That is normal on a quiet network.

Nodes are chosen by load, heartbeat freshness and a random term — not by where the client is, which the Control Plane neither knows nor asks. NODE_COUNTRY_CODE only matters when a client asked for that country.

So “no sessions” means there are few across the whole network right now, not that your region is wrong.

The node carries traffic but earns nothing

Look for Pushed events on EpochAttestations from your Control Plane’s signer. If there are none while traffic flows, intervals are being dropped instead of submitted. The usual reasons:

• The Control Plane’s signer has no ETH. It cannot send the transaction.
• The node does not sign its intervals. A Control Plane asks each node to sign before submitting and drops anything the node will not vouch for. A node and a Control Plane on different versions cause exactly this: the node does not recognise the request and stays silent.
• The traffic did not count. Time is held back until 64 KiB has moved since the last credited checkpoint, and if 10 minutes pass without that, the time is dropped. An idle tunnel earns nothing, by design.

A client cannot open an anonymous session

The refusal names its reason, in the words below. Each has its own fix:

The refusal says	What to do
access proof does not verify, permission proof does not verify	Check circuitVersion() against your artifacts, tree depth 16, and the point packing
... against a subscriber set this CP does not recognise	Your Merkle root is out of date — rebuild it from the registry and try again
this access claim has already been used	That slot’s nullifier is spent; use the next slot
access quota for this epoch is exhausted	Every slot for this epoch at this Control Plane is spent. Another Control Plane has its own, or wait for the next epoch
an anonymous session needs a permission from this window's packet	Take a permission for this window first — see permissions
this access slot has spent its node-time budget	That slot’s node time is used up; use the next slot
this permission of the subscription is already taken for this window	That number was taken this window, by another of your devices or earlier by this one. Ask for another number; the reply marks this case with index_taken
the permission index is beyond the published count	Numbers run from 0 to the count the issuer publishes, minus one
this permission has already been spent	It is held by a session that is still running. Use another of your permissions; this one is free about a minute after its session ends
no key is published for that issuer and window	The issuer has no key for this window — see below
anonymous access is not enabled on this CP, permissions are not enabled on this Control Plane	The directory names no SubscriberRegistry, or the Control Plane runs with SINGULA_PROTOCOL_ADDRESS=off and no SUBSCRIBER_REGISTRY_ADDRESS

If a client cannot take a permission at all, check that the issuer has a key for the current window: VoucherKeyRegistry.getEpochKey(issuerStarId, epoch). Keys can only be published for a future epoch, so a Control Plane started for the first time has none until the next epoch begins.

Contract reverts

SignerAlreadyRegistered

That signer address already belongs to another Star, and one address can sign for only one. Use a fresh identity, or call updateSigner on the Star that has it.

NotCP

The Star is acting as a Control Plane without the role, or someone is setting an endpoint on a Star that is not one. Check its current role: never granted, taken away, or now Banned.

NotStarOwner

The transaction does not come from the address the registry has as the owner. Connect that wallet.

EpochNotFuture

Someone is publishing a signing key for the current or a past epoch. VoucherKeyRegistry only accepts future epochs; that is what makes the key checkable. Wait for the next epoch — the Control Plane publishes its keys a day ahead.

GasBudgetExceeded

The Control Plane has used up its gas budget for this epoch. The budget is per Control Plane and resets when the epoch changes.

UnactivatedLimitExceeded

The receiving address already holds ten unactivated Orbits. Activate some, or send to another wallet.

The server or the hot key is compromised

The Star’s money is safe: rewards go to the owner, and the contracts read the payee from the registry.

1. Shut the compromised server down.
2. Bring up a clean one and take its new signer address from the startup banner.
3. From the cold wallet, press Rotate signer on the Star’s card in Stargate, or call updateSigner directly. The old key is cut off in the same transaction.

A node’s signer holds no ETH. A Control Plane’s holds only a little — see funding the signer — so there is nothing worth moving off the old address.

More on the two keys is in Stars and roles.