Troubleshooting

Common issues and how to resolve them.

Lima VM Issues

Lima VM won't start

Try: Settings → Docker → Restart Lima VM. If that fails, reset the VM completely from Settings → Docker → Reset Lima.

Docker commands are slow

Increase VM resources: Settings → Docker → CPU/Memory allocation. Restart after changes.

Connection Issues

Can't connect to Docker

1. Check menu bar icon is green. 2. Try restarting Lima VM. 3. Ensure no other Docker runtime is conflicting (Docker Desktop).

Kubernetes cluster unreachable

Verify kubectl works in Terminal: kubectl cluster-info. Check your VPN if connecting to remote clusters.

Homebrew Not Found After Installation

Setup guide still shows Homebrew as not installed

  1. After installing Homebrew, run the PATH commands shown in Terminal
  2. For Apple Silicon: Add /opt/homebrew/bin to your PATH
  3. For Intel: Add /usr/local/bin to your PATH
  4. Click "Refresh Status" in the Zenithal setup guide

Containers Not Showing

Containers screen is empty even though containers are running

  1. Check engine status — ensure the green dot is shown in the dashboard
  2. Click the refresh button in the Containers header
  3. Verify Docker is responding: In Terminal, run limactl shell default docker ps

Compose Project Won't Deploy

Error when deploying a docker-compose.yml file

  1. Validate your YAML syntax (use Compose Intelligence with Pro)
  2. Ensure all referenced images are available
  3. Check port conflicts — are the required ports already in use?
  4. Verify file paths for volume mounts are valid

Security Scan Fails

Image scan shows error or doesn't start

  1. Verify scanner is installed: trivy --version or grype version
  2. Update scanner databases: trivy image --download-db-only or grype db update
  3. Ensure the image exists locally (pull it first if needed)

High Memory Usage

Mac is slow, Lima VM using too much memory

  1. Stop unused containers to free memory
  2. Check the Resource Monitor for per-container memory usage
  3. Prune unused images: use the Image Library cleanup tools
  4. Adjust Lima VM memory allocation in Lima configuration
Zenithal general settings showing resource allocation and performance configuration

Disk Space Issues

Zenithal storage settings showing disk usage and storage location configuration

App Won't Open / Crashes on Launch

Zenithal won't open or crashes immediately

  1. Ensure you're running macOS 13.0 or later
  2. If macOS blocks the app: Go to System Settings > Privacy & Security and allow Zenithal
  3. Try deleting the app preferences: defaults delete mbu.Zenithal
  4. Reinstall from the latest DMG

License Issues

Subscription not showing in app

Make sure you're signed in with the same account you used to purchase on the website. Check your internet connection. Try signing out and back in. If issues persist, contact support.

Maximum devices reached

Sign out on unused devices from Settings → Account, or contact support to reset your device list.

Get More Help

Still having issues? Contact our support team with:

  • Zenithal version (Settings → About)
  • macOS version
  • Steps to reproduce the issue
  • Any error messages