Troubleshooting and resets

For problems with the MCP server itself, see MCP troubleshooting. This page is about the cluster.

Get more detail

Every command takes --log-level debug, or --debug for short. Logs go to standard error:

$ xianyun up --debug

Over MCP, the same output arrives in the tool result’s stderr.

A cluster won’t start

Confirm the driver’s program is installed and on your PATH: k3d version on Linux, colima version on macOS. xianyun doctor checks some of this.
Read the full error. Xianyun names the failing step.
If the cluster is stuck, recreate it:

$ xianyun destroy
$ xianyun up

Reset in three strengths

Restart. down stops the cluster and up starts it again. Nothing is removed from disk. Use this for an unresponsive cluster or a network problem.

$ xianyun down
$ xianyun up

Recreate. destroy deletes the cluster and its data. up builds a new one. Your config and the files under ~/.local/share/xianyun/, including the dev CA, stay.

$ xianyun destroy
$ xianyun up

Hard reset. Use this when recreating didn’t help. Replace <profile> with xianyun, or with the name k3d cluster list or colima list shows if you use the directory-hash naming strategy:

$ xianyun destroy
$ xianyun update-etc-hosts --remove
$ rm -rf ~/.local/share/xianyun/<profile>
$ xianyun up
$ xianyun ca trust
$ xianyun update-etc-hosts

If destroy fails and leaves a cluster behind, delete it with k3d cluster delete <profile> (Linux) or colima delete <profile> (macOS), then carry on. After a hard reset the CA is regenerated, so restart your browser to load the new one.

Over MCP, destroy, update-etc-hosts, and ca trust are gated, and the rm -rf is yours to run.

More than one cluster

By default there’s one cluster, named xianyun, per machine. To get one per directory, set the naming strategy:

cluster:
  name:
    strategy: directory-hash

With it, xianyun ca inspect in a temporary directory showed a profile like xianyun-tmp-82hnkhcc8c-260347, so each directory gets its own data under ~/.local/share/xianyun/. Hostname management still covers one cluster at a time unless you give each directory its own hostname.

Switching kubectl context

You don’t need to touch your kubeconfig. xianyun kubectl, xianyun k9s, and xianyun stern use the project’s cluster directly. To merge it into yours:

$ xianyun set-kube-context --use     # add it and make it current
$ xianyun set-kube-context --remove  # take it out again

If kubectl reports “connection refused” or “host is down”, check that the cluster is running with xianyun status.

Certificates

The CA lives in ~/.local/share/xianyun/<profile>/pki/current/, as ca.crt (safe to share) and ca.key (keep it local). It survives down and up, so you trust it once. To force a new one, delete the pki/ directory and run a command that needs it. See Trusting the dev CA.

Any HTTPS ingress backed by a configuration that declares both builtin:dev-ca and builtin:traefik-tlsstore should then show a valid certificate. That path hasn’t been deployed end to end (Known limitations).

Keyboard shortcuts