Skip to content

Troubleshooting

Inspect the context, test its connection, and locate the failing stage:

vsfleet config view --minify -n prod
vsfleet doctor prod
vsfleet cluster-info

vsfleet is not found

After installing with WinGet or Scoop, open a new terminal so it picks up the updated PATH, then run vsfleet --version.

For go install, the binary goes to go env GOBIN, or to the bin directory under go env GOPATH when GOBIN is empty. Add that directory to your PATH. On Linux or macOS with the default Go paths:

export PATH="$(go env GOPATH)/bin:$PATH"
vsfleet --version

Add the export to your shell startup file to keep it for new sessions. For a release archive, finish the sudo install step in Getting started.

The eight-stage diagnostic pipeline

vsfleet doctor checks the connection in order and reports the first failure:

  1. Configuration: validate TOML properties and context settings.
  2. Credentials: resolve the keyring, environment, file, or helper reference, or confirm prompt mode.
  3. Routing and proxy: check proxy reachability and authentication.
  4. DNS resolution: resolve locally or through the configured proxy.
  5. TCP handshake: connect to port 443.
  6. TLS negotiation: verify the trust chain or pinned thumbprint.
  7. SSO authentication: authenticate the configured vSphere user.
  8. API handshake: probe vSphere ServiceContent with read access.

Correct credentials, routes, or TLS policies at the failed stage.

Partial failures

Estate-wide commands keep healthy results when a vCenter fails. The terminal UI retains cached inventory with a stale-data warning.

If a context needs an interactive password, select it or reload it explicitly. Background refresh never interrupts the terminal with a password prompt.

Assessment database checks

If history operations fail, inspect the local ledger without contacting vCenter:

vsfleet db doctor
vsfleet db backup ./history-backup.db

Check database permissions and disk space. Back up before restoring or pruning; see Retention and recovery.