Troubleshooting / FAQ

:::note Placeholder page Ballast's stated bar is that a known failure gets a named cause and an offered action, not a raw error passed through. The entries below are the shape that bar produces; the real message text (quoted from the console, not paraphrased) will replace the illustrative text once captured. :::

The host does not appear after installing the agent

Check, in order:

1. The agent service (BallastAgent) is running on the host.
2. The agent's log (C:\ProgramData\Ballast\agent.log) for a connection error to the centre's gRPC address.
3. Firewall rules permit outbound traffic from the host to the centre's -listen/-advertise address.
4. The certificate the agent was issued at install time has not expired.

A host shows as "Autonomous"

This is not an error. It means the centre is currently unreachable from that host's agent, and the agent is continuing to enforce the last desired state it received — the product's core autonomy guarantee, working as intended. Once the centre is reachable again, the host reconciles ObservedGeneration and the indicator clears on its own.

A cluster shows healthy but every member is off

If Ballast itself issued a coordinated shutdown (for example, as part of planned maintenance), there is a grace window during which the cluster's last-known state can still read as healthy before the console reflects the shutdown. Confirm actual host power state directly rather than trusting a cluster-level summary alone if this looks wrong.

A migrated Linux VM appears to have lost its disk

This is almost always the initramfs/dracut image built for the source hypervisor's storage drivers, not a real loss of data. See the VMware migration guide.

An iSCSI target the console shows is not one I declared

An undeclared target discovered on a host is not necessarily a fault — it may be visible from prior configuration outside Ballast. Use Rediscover before assuming the target list is wrong.

Console pages hang or time out

If a backing NAS, file server, or switch that Ballast has no agent presence on becomes unreachable, any page that depends on data from it can hang rather than failing fast. This is being tightened; if you hit it, note which page and what was unreachable — that is a defect in Ballast's error handling, not something to work around.

General principle

If fixing something requires opening a PowerShell session directly on a host, that is treated as a defect in Ballast, not a documented workaround — please report it rather than filing the workaround away as normal.