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 directoryThe 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 repairRun 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 fixingmacOS — re-trust the CA:
sudo msh local repair --trust-caLinux — 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-trustGo-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 listApprove 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 applyPolicy 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.yamlOr view the policy the daemon is actually enforcing:
msh local policy showHost 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 summaryCheck the pinned list:
msh local pinnedIf 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 listHTTPS_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 enforcemsh local doctor reports failures
Run msh local repair to fix most issues automatically:
msh local repairFor macOS CA trust issues specifically:
sudo msh local repair --trust-caPass --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.