Troubleshooting
This page maps the symptoms you see when running Clustron Zaris to their likely causes and the fixes that resolve them. It is organized by where the problem shows up: connecting to managers, creating and starting stores, forming the cluster, connecting clients, and reading metrics. Start with the table that matches your symptom.
Before diving in, two checks resolve a large share of problems: confirm you have an active workspace in the current session (Get-ZrWorkspace), and confirm the relevant ports are open. Use Get-ZrStore at any point to inspect the current state of the cluster.
Cannot connect to a manager
A cmdlet reports no manager connection, or a workspace shows fewer reachable managers than you listed.
| Symptom | Cause | Fix |
|---|---|---|
| Timeout or connection refused | The Management Service is not running | Confirm Clustron is installed and the service is started on the target server |
Refused on port 7801 | Firewall blocks the management port | Allow inbound TCP 7801 on the server and any firewall in between |
| Some managers unreachable in the roster | An endpoint is wrong or unreachable | Verify each address and port; check connectivity between machines |
| Works locally, fails from another host | You used localhost or 127.0.0.1 | Use the server's real IP or hostname for multi-server clusters |
Store fails to create or start
New-ZrStore reports an error, or Start-ZrStore leaves a node down.
| Symptom | Cause | Fix |
|---|---|---|
| "No active Zaris manager connection" | No workspace is active | Activate a workspace first, or pass -Managers |
| "cannot be created here — this is an attach-mode manager" | The manager runs in attach mode | Adopt the externally-run store with Register-ZrStore |
| Error on one manager, success on others | That manager is unreachable | Confirm every manager is running and reachable, then retry |
| Node fails to launch on start | A cluster or client port is already in use | Pick free -BaseClusterPort / -BaseClientPort ranges; avoid overlapping stores |
| "port range … overlap" on create | The base ports are too close for the per-server process count | Widen the gap between -BaseClusterPort and -BaseClientPort |
Nodes do not join the cluster
The store starts but Get-ZrStore reports Partial, or only some nodes appear.
| Symptom | Cause | Fix |
|---|---|---|
| Only some nodes are visible | Cluster ports blocked between machines | Open the cluster range (default 7811–7850) across the network |
| Cluster never forms | Not all managers were in the workspace when the store was created | Activate a workspace with every manager, then re-create the store |
| Nodes on other servers unreachable | Wrong or unreachable addresses | Use reachable IPs or hostnames — not localhost — and verify connectivity |
Clients cannot connect
An application or the ClientShell fails to reach the store.
| Symptom | Cause | Fix |
|---|---|---|
| Connection fails | The store is not running | Start the store with Start-ZrStore; confirm Running with Get-ZrStore |
| Connection refused on the client port | Client ports blocked | Open the client range (default 7861–7899) |
| Wrong endpoint | Incorrect host or client port supplied | Connect with the correct <host>:<clientPort> for a running node |
No metrics displayed
Watch-ZrStoreMetrics shows no rows, all-zero totals, or stops updating.
| Symptom | Cause | Fix |
|---|---|---|
| No rows or all-zero totals | The store is stopped, or no client is sending traffic | Confirm Running with Get-ZrStore; generate load with client operations |
| Totals rise but one node column stays flat | That node is down or unreachable | Check the node with Get-ZrStore; start it if stopped |
| View stops updating | Client activity stopped, or a manager became unreachable | Verify clients are active and the managers are reachable |
| "No managers connected" | No workspace is active | Activate a workspace, or pass -Managers |
General guidance
A few habits prevent most of the problems above:
- Always activate a workspace before any other admin command, and confirm its managers with
Get-ZrWorkspace. - Verify port and firewall settings early — especially the cluster and client ranges across the network on multi-server clusters.
- Use
Get-ZrStoreto inspect cluster state whenever behavior is unexpected. - Start with a single-server cluster to validate your workflow before scaling out to multiple servers.
Next steps
- Ports and networking — the exact ranges to open.
- View store information — inspect state while diagnosing.
- Deployment overview — deployment models and platform-specific setup.