Troubleshooting

Homebrew Not Detected

If Tappie shows "Homebrew not found":

1. Verify Homebrew is installed:

   brew --version

2. If not installed, install Homebrew:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Check Homebrew path:
   • Apple Silicon: /opt/homebrew/bin/brew
   • Intel: /usr/local/bin/brew
4. Restart Tappie after installing Homebrew

Homebrew Commands Failing

If operations like install or upgrade fail:

1. Update Homebrew:

   brew update

2. Run Homebrew diagnostics:

   brew doctor

3. Follow any recommendations from brew doctor

Package Installation Fails

Common causes and solutions:

Fixing Permissions

If you see permission errors:

# For Apple Silicon Macs
sudo chown -R $(whoami) /opt/homebrew

# For Intel Macs
sudo chown -R $(whoami) /usr/local

Cask Installation Blocked

If macOS blocks a cask installation:

1. Open System Settings → Privacy & Security
2. Look for a message about the blocked app
3. Click Open Anyway
4. Or, right-click the app and select Open

Slow Package List Loading

If the package list takes a long time to load:

• First launch - Initial sync downloads package database (one-time)
• Many packages - Consider filtering by installed only
• Outdated cache - Click Refresh to clear and reload

High Memory Usage

Reduce memory usage by:

• Closing the dependency graph when not in use
• Using filters to show fewer packages
• Disabling package icons in Settings

Package Not Found

If you can't find a package:

1. Press Enter to search the remote Homebrew repository
2. Check spelling and try alternative names
3. Search on formulae.brew.sh to verify it exists
4. The package may require adding a tap first

Search Not Updating

If search results don't update:

• Click Refresh (Cmd+R) to reload the package list
• Clear the search box and try again
• Check if filters are limiting results

Updates Not Showing

If outdated packages aren't detected:

1. Click Update Homebrew (Cmd+Shift+U) to fetch latest info
2. Wait for the update to complete
3. Click Refresh to reload package statuses

Upgrade Fails

If a package won't upgrade:

• Check the Activity Log for specific error
• Try reinstalling: select package and click Reinstall
• Manually upgrade in Terminal:

  brew upgrade package-name --verbose

"Cannot write to /usr/local/Cellar"

Fix permissions:

sudo chown -R $(whoami) $(brew --prefix)/*

"Error: No such file or directory"

The Homebrew installation may be corrupted. Try:

brew update-reset

"Error: Xcode Command Line Tools"

Install or reinstall Xcode CLT:

# Remove existing (if corrupted)
sudo rm -rf /Library/Developer/CommandLineTools

# Reinstall
xcode-select --install

Free Up Disk Space

Homebrew caches downloads and old versions:

# See what can be cleaned
brew cleanup -n

# Actually clean up
brew cleanup

Remove Unused Dependencies

Clean up orphaned dependencies:

brew autoremove

Check Activity Log

The Activity Log panel shows real-time output from Homebrew commands. Expand it to see detailed error messages when something fails.

Homebrew Documentation

For Homebrew-specific issues, consult:

• Homebrew Documentation
• Homebrew Discussions

Contact Support

If you're still having issues:

• Email us at contact@empiricapps.com
• Include the error message from the Activity Log
• Include your macOS version and Mac model

As a last resort, reset Tappie to default state:

1. Quit Tappie
2. Delete Tappie preferences:

   defaults delete com.empiricapps.tappie

3. Delete cached data:

   rm -rf ~/Library/Caches/com.empiricapps.tappie

4. Relaunch Tappie