diff --git a/website/docs/troubleshooting/troubleshooting-podman-on-macos.md b/website/docs/troubleshooting/troubleshooting-podman-on-macos.md index b47d4454fcd69..79da838c39f31 100644 --- a/website/docs/troubleshooting/troubleshooting-podman-on-macos.md +++ b/website/docs/troubleshooting/troubleshooting-podman-on-macos.md @@ -117,3 +117,46 @@ After a failed start, the Podman machine might be unable to start because a QEMU #### Solution Use Podman 4.6.1 or greater. + +## Podman machine not starting with QEMU 8.1.0 from brew + +When you installed Podman and QEMU with brew, and QEMU version is 8.1.0, Podman machine might fail to start with an error such as: +`Error: qemu exited unexpectedly with exit code -1, stderr: qemu-system-x86_64: Error: HV_DENIED` + +#### Solution + +- [Install Podman Desktop and Podman using the .dmg installer](https://podman-desktop.io/docs/Installation/macos-install) rather than brew. + The Podman installer has a QEMU binary that has been tested with Podman. + +#### Workaround + +Keep your brew-based installation and apply one of these workarounds: + +- Rollback the QEMU brew package to v8.0.3. + + ```shell-session + $ brew uninstall qemu + $ curl -OSL https://raw.githubusercontent.com/Homebrew/homebrew-core/dc0669eca9479e9eeb495397ba3a7480aaa45c2e/Formula/qemu.rb + $ brew install ./qemu.rb + ``` + +- Alternatively, sign the QEMU brew binary locally: + + ```shell-session + $ cat >entitlements.xml < + + + + com.apple.security.hypervisor + + + + EOF + $ codesign --sign - --entitlements entitlements.xml --force /usr/local/bin/qemu-system-$(uname -m | sed -e s/arm64/aarch64/) + ``` + +#### Additional resources + +- [Homebrew issue #140244](https://github.com/Homebrew/homebrew-core/issues/140244). +- [Podman issue #19708](https://github.com/containers/podman/issues/19708).