troubleshooting.md

Troubleshooting

Homebrew not found or broken

Run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/opt/homebrew/bin/brew shellenv)"
brew doctor

Then re-run installer.

node is not 24.x after install

Run:

brew link --overwrite --force node@24
node --version

python3 is not 3.13

Run:

brew link --overwrite --force python@3.13
python3 --version

opencode not found in non-interactive shell

Installer places opencode under ~/.opencode/bin.

Run:

source ~/.zshrc
zsh -ic 'opencode --version'

Flutter doctor reports Android/Xcode issues

Run:

xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
flutter doctor -v

If Android SDK licenses are pending:

flutter doctor --android-licenses

Docker context is not OrbStack

Run:

docker context use orbstack
orbctl start
docker context ls
docker context use colima

If neither context exists, run a clean bootstrap for container modules:

./install-macos.sh --skip-health-check

Kubernetes CLI/tooling missing or not found

Run:

brew update
brew install kubernetes-cli helm kustomize kind minikube kubectx k9s
kubectl version --client=true
helm version --short
kind version
minikube version

kind/minikube cluster commands fail

Run:

kind get clusters
minikube status
docker context ls

If Docker runtime is not available, start a container runtime first (OrbStack/Docker context or Colima) and re-run install-macos.sh.

Deterministic recovery sequence:

docker context ls
docker context use orbstack || docker context use colima
if command -v orbctl >/dev/null 2>&1; then orbctl start; fi
kind delete cluster --name test || true
kind create cluster --name test

Wrong Gemini package installed

gemini cask is a GUI cleaner app, not Gemini CLI.

Run:

brew uninstall --cask gemini || true
brew install gemini-cli
gemini --version