Troubleshooting¶

When Patcher misbehaves, turn on debug logging, then jump to your symptom.

Debug Logging¶

Every command takes a root-level --debug (or -x), placed before the subcommand. It streams DEBUG-level logs to your terminal and hides the spinner so they stay readable.

Run any command with verbose output¶

$ patcherctl --debug export --path ~/reports

Those logs are written to ~/Library/Application Support/Patcher/logs/patcher.log with or without --debug. Attach that file when you report a bug.

Exit Codes¶

patcherctl returns a distinct code per failure class, so CI and scripts can branch on it.

Code	Meaning
`0`	Success
`1`	Handled error (a `PatcherError` or user-facing issue)
`2`	Unhandled exception
`3`	Setup error
`4`	API error, such as an unauthorized or invalid response
`130`	Interrupted with Ctrl+C

Command Not Found¶

If patcherctl --version comes back with command not found, the package installed fine but landed outside your shell’s PATH. Adding your Python user-base bin directory fixes it, covered on the install page under Adding to Environment Path.

Authentication Failures¶

A 401 or 403 from Jamf means the stored credentials are missing a privilege, expired, or simply wrong. Re-run the wizard with patcherctl --fresh to re-enter them, or do a full reset to clear everything and start over.

Known Issue

If a Standard setup failed after it created the Jamf API role and client, the next Standard run also fails with a 401, because those objects already exist. Delete the role and client in Jamf and retry, or switch to SSO setup to reuse what Patcher already created.

Certificate Errors¶

Patcher trusts whatever your Mac trusts. On a network behind a TLS-inspecting proxy (Zscaler, Netskope, Palo Alto GlobalProtect, and the like), it works as long as your company’s certificate is in the system keychain, which your MDM usually installs for you. If your browser can reach Jamf without a security warning, Patcher can too. The SSL verification section on the install page has the background.

When Patcher fails with a network error that mentions certificate verification, two checks cover almost every case.

Confirm the company certificate is installed

In Keychain Access, look under the System keychain for your organization’s root certificate authority.

Confirm the MDM profile has applied

A newly enrolled Mac sometimes lacks the certificate until its next check-in.

Catalog API Blocked by Web Filtering¶

Patcher matches titles against the public catalog API at api.patcherctl.dev. On a corporate network, a secure web gateway (Netskope, Zscaler, Palo Alto, and the like) can block or restrict that domain because it is new and not yet categorized, which surfaces as an API error during matching, or a block page if you open the site in a browser. This is not a certificate problem: the connection is refused or rewritten by policy, not by a missing trust anchor.

Confirm it from the affected network:

A reachable API returns a small JSON health payload¶

$ curl https://api.patcherctl.dev/health
{"status":"ok"}

Anything other than that JSON, such as a redirect, a block page, or a read-only notice, means a web filter is in the way. Two ways forward:

Ask IT to allowlist the domain

Have your security team allow *.patcherctl.dev in the web gateway. The domain has been submitted to the major URL-filtering vendors for categorization as Computer and Internet Info, so access also improves on its own as the domain’s reputation builds.

Point Patcher at your own catalog

Set the PATCHER_API_URL environment variable to override the API root. Self-hosting covers running your own instance.

Empty or Stale Data¶

When a report is missing data or looks out of date, it’s usually one of these.

Every title has an empty install_label

Installomator matching is switched off. Turn it back on per Disabling Installomator Matching.

The numbers look out of date

Analysis reads the most recent cached report. Clear the cache with patcherctl reset cache, then re-run to pull fresh data from Jamf.

Start Over¶

A full reset wipes credentials, UI configuration, setup state, and cached data, then re-runs the wizard. It’s the fastest way to rule out a corrupt local state.

Wipe all local state and re-run setup¶

$ patcherctl reset full

If a reset doesn’t help, reinstall the package.

$ uv pip install --reinstall patcherctl

pip

$ python3 -m pip install --force-reinstall patcherctl

Still Stuck?¶

File a GitHub issue with the command you ran, the full error output, and your patcher.log. For a back-and-forth, the maintainers are in the #patcher channel on MacAdmins Slack.