Troubleshooting

Status: Available.

Common issues and their solutions.

Daemon is not running

msh local status
# Error: dial unix /Users/you/.mezite/local/daemon.sock: connect: no such file or directory

The daemon is not running. Start it:

# Reinstall (idempotent) and wait for the socket to appear
msh local install

# Diagnose and repair an existing service installation
msh local doctor
msh local repair

Run msh local doctor for a full diagnostic of permissions, the service unit, and the daemon process. Run msh local repair to fix anything doctor flags.

TLS certificate errors

Your CLI tool is rejecting the msh local dev CA certificate.

Check trust state:

msh local ca info
# trust: untrusted  ← needs fixing

macOS — re-trust the CA:

sudo msh local repair --trust-ca

Linux — add the CA to the system trust store:

# Debian / Ubuntu
sudo cp ~/.mezite/local/ca.crt /usr/local/share/ca-certificates/mezite-local-ca.crt
sudo update-ca-certificates

# RHEL / Fedora
sudo cp ~/.mezite/local/ca.crt /etc/pki/ca-trust/source/anchors/mezite-local-ca.crt
sudo update-ca-trust

Go-based tools and Python / Node / AWS CLI read the env vars set by msh local shell-init, not the system trust store. Ensure the snippet is sourced:

eval "$(msh local shell-init)"

This sets SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS, AWS_CA_BUNDLE, and GIT_SSL_CAINFO to $HOME/.mezite/local/ca-bundle.pem (system roots merged with the msh local dev CA).

A CLI command hangs indefinitely

The request was classified as modify, sensitive, or break-glass and is waiting for approval. Check pending approvals:

msh local approval list

Approve or deny:

msh local approval allow <id>
msh local approval deny  <id>

If approval list is empty, the proxy mode may be set to observe or off rather than enforce, or the policy for that request is set to deny (which returns immediately, not hang). Verify:

msh local status
# proxy_mode    enforce   ← must be enforce for policy to apply

Policy changes are not taking effect

Policy is hot-reloaded via fsnotify. If a reload fails (invalid YAML), the daemon logs an error and enforces the last-good policy. Check daemon status for parse errors:

msh local status
# policy    loaded (operator policy.yaml failed to reload: ...)

Validate the candidate before saving:

msh local policy validate --path ~/.mezite/local/policy.yaml

Or view the policy the daemon is actually enforcing:

msh local policy show

Host is not being intercepted

The host is not in any inspect: list in policy.yaml, or the host is on the user pinned (never-MITM) list.

Check the inspect list:

msh local inspect summary

Check the pinned list:

msh local pinned

If the host appears in the pinned list and should not, remove it:

msh local unpin <host>

If the host appears in the detector pin cache (auto-detected cert-pinned hosts), it will splice through without MITM:

msh local detector list

HTTPS_PROXY is set but traffic is not going through msh local

The shell-init snippet sets HTTPS_PROXY only when the daemon is running. If you source the snippet before starting the daemon, the variable is unset. Re-source after the daemon starts:

msh local install
eval "$(msh local shell-init)"

Some tools ignore HTTPS_PROXY for localhost/127.0.0.1 destinations, even with an empty NO_PROXY. A loopback cluster endpoint is distinct from the proxy listener. For kubectl, set proxy-url: http://127.0.0.1:9443 in the cluster's kubeconfig entry alongside its CA bundle, as shown in the Quickstart. Keep server pointing at the actual cluster endpoint.

Commands are slow even for read operations

Classification and policy evaluation normally add sub-millisecond overhead. Compare passthrough and enforce mode to isolate proxy overhead from upstream latency:

# Temporarily bypass (does not stop the daemon)
msh local set-proxy-mode passthrough
kubectl get pods   # if this is fast, upstream was fine all along
msh local set-proxy-mode enforce

msh local doctor reports failures

Run msh local repair to fix most issues automatically:

msh local repair

For macOS CA trust issues specifically:

sudo msh local repair --trust-ca

Pass --dry-run to see what repair would do without making changes.


Still stuck? Open an issue on GitHub or reach out via the Pricing page to talk to engineering.