Troubleshooting

Fixes for the most common Brewwery and Homebrew problems. If yours is not here, open an issue and use Settings → About → Report a problem…, which opens a pre-filled issue you can review first.

Brewwery says “Homebrew not found”

Brewwery looks for /opt/homebrew/bin/brew, /usr/local/bin/brew, and brew on your PATH.

Check that Homebrew is installed. In Terminal:
```
which brew && brew --version
```
If nothing is printed, install Homebrew — see What is Homebrew?.
If Homebrew is somewhere else, copy the path printed by which brew into Settings → Custom Homebrew path, click Validate, then Save.
Click Refresh data on the Dashboard.

Apps started from the Finder do not read your shell profile, so a brew that only exists because of PATH changes in ~/.zshrc may not be found. Setting a custom path fixes that.

The custom path does not validate

The path must be absolute, point to the brew executable itself (not its folder), and brew --version must succeed. Run the path in Terminal to see the error:


/path/to/brew --version

If Homebrew itself is broken, run brew doctor in Terminal and follow its advice.

Lists are empty or out of date

Press ⌘R to refresh the current page — Brewwery does not watch for changes made in Terminal.
Package information comes from Homebrew’s local data. On Updates, click Check for updates to run brew update, then refresh.

Search shows “Use Latin characters”

Homebrew package names only use ASCII letters, digits, and @, -, _, ., +. Search for the package’s English name, for example postgresql rather than a localized name.

”Another Homebrew operation is already running”

Brewwery runs one operation that changes Homebrew at a time, including metadata updates, taps, and pinning. Wait for the current operation to finish, or cancel it from the progress panel. This guard covers Brewwery only: avoid simultaneous changes from Terminal or another app.

An install or upgrade is stuck

Large packages can take a long time to download or build. The progress panel shows Homebrew’s live output — if it is still changing, the operation is still working.

To stop it, click Cancel. Brewwery stops Homebrew and every process it started. Operations also stop by themselves after their safety timeout (45 minutes for install and upgrade).

An operation failed

The progress panel stays open with the error, and bounded output is saved in History. Large logs show a marker when trimmed. Lists refresh after failure or cancellation because Homebrew may already have applied part of a change. The last lines usually explain the problem. Common causes:

Output mentions	Try
`Permission denied`, `not writable`	Fix ownership of the Homebrew prefix as `brew doctor` suggests
`Could not resolve host`, `Failed to connect`	Check your internet connection, VPN, or proxy
`Xcode` or `Command Line Tools`	Run `xcode-select --install`, or update the tools in System Settings
`already installed`	Refresh the page — the package is already there
`It seems there is already an App`	A cask’s app exists in /Applications from another source; remove it or install in Terminal with `--force`
`requires macOS`	The package does not support your macOS version

Services will not start

Open the service’s File path in Terminal to check its configuration.
Run brew services info <name> in Terminal for details.
Some services must be initialized first — for example, databases often print setup steps in their caveats. Open the package’s details to read them.

The Dock badge and the app disagree

Since 1.0.1 the badge, sidebar, status bar, and menu bar share the same outdated list. If the number looks wrong, refresh the list: it is re-read in the background every 30 minutes, and ⌘R on the Updates page re-reads it now. Report a persistent mismatch with the installed app version and a screenshot.

The count also only knows about updates Homebrew has already fetched. Run Check for updates on the Updates page to run brew update first.

To hide the badge entirely, turn it off in Settings → Dock.

Brewwery does not update itself

Check Settings → Application updates and click Check for updates now.
Updates require the downloaded release; a copy built from source does not update automatically.
Make sure Brewwery is in /Applications and not running from the disk image.
Finish any Homebrew operation before installing and relaunching. Version 1.1.1 waits for pending local saves on normal quit and asks before discarding a failed save.
Native 1.x releases use Sparkle. Electron 0.9.x requires a manual DMG install.
If an update reports a signature or download error, do not disable verification. Download the release DMG from the official website or GitHub and report the error.

Favorites or History will not save

Version 1.1.1 saves JSON in the background and shows read/write failures instead of hiding them. Check available disk space and access to ~/Library/Application Support/Brewwery/, then use Retry in the app. Do not delete the folder as a first troubleshooting step.

New changes remain in memory after a failed write. Normal quit waits for pending saves; if a save failed, keep the app open and retry unless you explicitly want to discard unsaved changes. Force-quit or power loss can lose pending changes.

If a JSON file cannot be read, a later save first preserves it as an .unreadable-<UUID>.bak file. Keep that backup if you need to recover previous data. Initial JSON loading and manual History export are still synchronous.

Starting over

To reset Brewwery without touching Homebrew, quit it and remove its data:


defaults delete com.brewwery.app
rm -rf "$HOME/Library/Application Support/Brewwery"

Collecting logs

Brewwery writes to the unified log. To watch it while you reproduce a problem:


log stream --level info --predicate 'subsystem == "com.brewwery.app"'

Logs stay on your Mac unless you choose to share them.