Pulsar NetworkPULSARNETWORK ← Back to dashboard
Operator knowledge base

Xandeum pNode tips & troubleshooting

Running a Xandeum pNode is mostly smooth, but a handful of gotchas can cost you real time (or your node). These are the hard-won fixes we hit while running a fleet of 12 pNodes, written down so you do not have to learn them the hard way. Each tip has its own link, so you can share a direct answer to anyone's question.

This is a living page. Hit a problem that is not here, or have a better fix? Tell us on X or via our community links and we will add it, then send you the direct link to the answer.

Jump to a fix
  1. Back up your identity key
  2. Update did nothing (held package)
  3. Keep your identity on update
  4. Keep pRPC private
  5. Verify after every change
  6. Node missing from get-pods
  7. Self-monitor with pRPC
  8. Don't mix devnet & mainnet
  9. Storage shows ~0% used
  10. Ports, SSH & security
  11. Reach the GUI safely
  12. Know your reward streams
  13. Dedicate your storage
  14. Portal won't load (RPC)
  15. "Expected Signer mismatch"
  16. Rebuilding? Restore the key
  17. When the installer is done

Setup & identity

1.Back up your identity key before anything else #

Your pNode's keypair lives at /local/keypairs/pnode-keypair.json. This file is your node's identity, it ties every reward and your standing to you. Copy it somewhere safe and off the server (a USB stick, a password manager, an encrypted backup) the moment the node is up, and again before any update.

Real story from the operator community: someone changed laptops, never copied this file, and the old laptop got recycled. The key was gone for good, and so was the node's identity. There is no way to regenerate the same key.

2.Keep your pRPC private, not public #

The installer's example command hardcodes --prpc-mode public (which binds pRPC to 0.0.0.0 and exposes it to the open internet). It is very easy to copy that example by accident and quietly run your node with a public pRPC. Run it private instead:

bash install.sh --non-interactive --update --default-keypair \
  --prpc-mode private --atlas-cluster devnet --operator-revenue 1000

Then confirm it is bound to localhost:

systemctl cat pod.service | grep -- '--rpc-ip'
# you want: --rpc-ip 127.0.0.1

Updating without breaking things

3.Your update "worked" but the version didn't change #

If you pinned the pod package with apt-mark hold pod (a good way to control when you upgrade), the installer's "upgrade / accept defaults" path will look like it succeeded, but pod --version stays on the old version, because apt is keeping the held package. You have to unhold first:

apt-mark unhold pod
wget -O install.sh "https://raw.githubusercontent.com/xandeum/xandminer-installer/refs/heads/master/install.sh" && chmod +x install.sh
bash install.sh --non-interactive --update --default-keypair --prpc-mode private --atlas-cluster devnet --operator-revenue 1000
apt-mark hold pod
Use --atlas-cluster mainnet-alpha instead of devnet for a mainnet node. This silent no-op is the single most confusing pNode update gotcha.

4.Don't let an update regenerate your key #

The installer can offer to "generate a new keypair." If you say yes, your node gets a new identity and your existing stake and standing detach from it. Always update with --default-keypair (it reuses the key you already have), and after the update, check that your public key is unchanged against your own records.

5.Verify after every change #

Updates touch the install, so it pays to run a quick checklist afterwards rather than assuming it worked:

pod --version                                              # right version?
systemctl cat pod.service | grep -oE -- '--(devnet|mainnet-alpha)|--rpc-ip [0-9.]+'  # right cluster + private?
systemctl is-active pod.service                            # active?

Monitoring & data

6.Your node is "missing" from get-pods #

A node omits itself from its own get-pods roster. So if you query get-pods on your own machine and don't see your node, that is expected, not a fault. Confirm it is gossiping by checking from another node or on the portal.

7.You can self-monitor over pRPC (no third party needed) #

Your own node will answer pRPC calls on localhost. The most useful method is get-pods-with-stats, which returns the full gossip roster with per-node storage (committed and used), uptime and version. It works on both devnet and mainnet pods:

curl -s -X POST http://127.0.0.1:6000/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"get-pods-with-stats","id":1}' | jq
Other methods: get-pods (roster) and get-stats. This is how you build your own monitoring without depending on anyone else's infrastructure, it is exactly what powers our live network numbers.

8.Don't mix devnet and mainnet builds #

Devnet and mainnet run on different pod versions and clusters. Pin your mainnet node's version with apt-mark hold pod and never push a devnet build onto a mainnet node (or vice versa). After any update, double-check the cluster flag (--devnet or --mainnet-alpha) so a node didn't quietly switch sides.

Storage & rewards

9.Storage shows almost no usage, and that's fine #

You commit storage with the "Dedicate and Earn" button, but on an early network the used portion stays near zero, so STOINC payouts are near zero too. That is normal supply-ahead-of-demand behaviour, not a misconfiguration. Just make sure storage is actually dedicated. To see what rewards could look like as usage grows, try our rewards calculator.

Networking & security

10.Open only the ports you need, and lock down SSH #

A pNode uses a small, known set of ports (per the docs): TCP 6000 (pRPC) and 7000 (ingest); UDP 5000, 7001, 7002, 9001 (gossip / atlas). Run a default-deny firewall that allows only those plus SSH, use key-only SSH (disable password login), and add fail2ban.

A weak SSH password is how nodes get owned. In our experience the one box left on a password login got hit by a crypto-miner, while the key-only, firewalled boxes were untouched. Harden first, not after.

11.Reach the GUI safely (don't expose 3000/4000) #

The xandminer GUI (port 3000) and its API (port 4000) should not be open to the internet. Keep them closed at the firewall and reach them over an SSH tunnel instead:

ssh -i <your-key> -L 3000:localhost:3000 -L 4000:localhost:4000 root@<your-node> -N
# then open http://localhost:3000 in your browser

Rewards & claiming

12.Know your reward streams, and where each one lives #

A pNode can earn from more than one place, and they show up on different screens, which is where most "where are my rewards?" confusion comes from:

The classic trap is the DAO / merkle one: the XAND is there, it just isn't on the page people expect to find it.

13.Dedicate your storage, or you earn nothing #

Having the node online is not enough, you have to commit storage. Do it from the GUI with the "Dedicate and Earn" button (port 3000), or via the xandminerd API on port 4000:

curl -s -X POST http://127.0.0.1:4000/drive/dedicate \
  -H "Content-Type: application/json" -d '{"space":<GB>,"path":"/"}'

If you never dedicate, the node runs but contributes zero storage, so it cannot earn. Re-check it after any rebuild or update.

Managing your node in the portal

14.The owner portal won't load your nodes? Swap the RPC #

The owner / staking portal reads on-chain data through an RPC endpoint, and the default RPC is flaky, the /owner view often fails to load or shows nothing. If your nodes or balances won't appear, point the portal at a reliable mainnet RPC (a Helius endpoint, for example) instead of the default. It is almost always an RPC problem, not your node.

15."Expected Signer mismatch" when binding a key #

If you try to bind or change a key in the portal and get "Expected Signer mismatch," you are signing from the wrong machine. The action has to be signed by the keypair it concerns: to change a devnet key, do it from (an SSH tunnel to) the devnet node; for a mainnet key, the mainnet node. Match the signer to the node and the error clears.

Recovery & install

16.Rebuilding a node? Restore the key, or it's a new node #

If you ever wipe and rebuild a box (OS reinstall, moving hosts, recovering from a compromise), the pod reinstall generates a brand-new identity unless you put your saved keypair back at /local/keypairs/pnode-keypair.json first. A new identity means re-registering and re-staking from scratch, and any rewards already allocated to the old key can get stranded (recovering them becomes a support / admin task, not something you can do yourself). This is the real reason tip 1 matters: restore the key, and the rebuilt node is the same node.

17.Know when the installer actually finished #

The installer runs for several minutes. It is done when you see messages like "setup completed successfully," "upgrade completed successfully," "xandminerd service running on port 4000," and "service restart completed." Then confirm the version in the GUI (port 3000 over your tunnel) and check storage is still dedicated. Don't assume it finished just because the terminal scrolled.

New to running a node?

Start with our step-by-step guide to running a Xandeum pNode, then come back here when you hit a snag. Want to know what a node earns? See the rewards calculator.

Run a pNode → Ask us a question
Written from real experience running a fleet of 12 Xandeum pNodes, cross-checked against the official Xandeum docs. Flags and paths reflect pod 1.4.x; always confirm against the current docs and installer. An independent community resource by Pulsar Network, not affiliated with or endorsed by the Xandeum Foundation. Not financial advice.