Troubleshoot the local setup

For local-setup specific issues, also check the local-setup issues in the helm-charts repository.

Docker or Podman is not running

Start Docker Desktop or Podman before running the setup.

For WSL2, verify Docker Desktop WSL integration is enabled.

Ports are already in use

The local setup expects ports 8443, 80, and 443 to be available. Stop conflicting services before running setup.

Kind cluster creation fails

Delete the existing Kind cluster and retry:

kind delete cluster --name platform-mesh
task local-setup

Check available disk space. The setup needs about 10 GB. Also verify that the container runtime has enough CPU and memory.

Browser certificate warnings

Reinstall local certificates:

mkcert -install

If warnings continue, see the certificate troubleshooting guide.

Component timeouts

Verify that all required images can be pulled from your network. To reduce image pulling on subsequent runs, see Speed up local rebuilds.

Enable debug output

Prepend DEBUG=true to any setup task:

DEBUG=true task local-setup:iterate

WSL2 cgroup issues

If Kubernetes crashes because of a cgroup v1 and v2 hybrid state, force WSL2 to use cgroup v2.

Open PowerShell, edit %USERPROFILE%\.wslconfig, and add:

[wsl2]
kernelCommandLine = cgroup_no_v1=all

Restart WSL2 after saving the file.

Clean up the local setup

kind delete cluster --name platform-mesh
mkcert -uninstall