Troubleshooting

Troubleshooting

Setapp must be running

The XPC service is hosted by Setapp's LaunchAgent. If Setapp isn't running, commands will fail with a connection error.

Fix: Open Setapp.app, or check that the LaunchAgent is loaded:

launchctl list | grep setapp

App not found in Setapp catalogue

The app name must match exactly as it appears in Setapp. Names are case-sensitive and may include version numbers (e.g. Bartender 5, not bartender).

Fix: Run setapp-cli list to see the exact names of installed apps, or check the Setapp app catalogue for the correct name.

XPC request timed out

Install requests have a 180-second timeout. This can happen if Setapp is busy or the network is slow (Setapp may need to download the app).

Fix: Try the command again. If it persists, restart Setapp.

Build fails

The most common cause is missing Xcode Command Line Tools.

Fix:

xcode-select --install

Building a universal binary (make build) requires full Xcode. If you only have Command Line Tools, the build will fail with an error about xcbuild.

Debug output

For detailed diagnostics, run any command with the --debug flag:

setapp-cli install Proxyman --debug

Or set the environment variable:

SETAPP_DEBUG=1 setapp-cli install Proxyman

This prints debug information to stderr, including XPC connection details and framework loading status.