Troubleshooting#

For a list of Patcher exit codes and viewing help, visit the usage page.

Debugging#

By default, logs written to Patcher’s log file are INFO and higher. Running the same command with the --debug flag will show all levels of logs to stdout and the log file.

$ patcherctl <command> <options> --debug

Interpreting Patcher Logs#

Patcher’s log(s) are stored in the Application Support directory of the user library: ~/Library/Application Support/Patcher/logs. There are three potential log files depending on configuration:

  1. patcher.log: The primary log file used when any Patcher command is invoked.

  2. patcher-agent.out.log: Standard out (stdout) log used by the LaunchAgent.

  3. patcher-agent.err.log: Errors (stderr) logged by the LaunchAgent.

Each log entry contains a timestamp, the child logger writing the log, and log level.

Sample log#

Sample error
2024-12-30 21:19:35,423 - Patcher.ApiClient - ERROR - Client error (401): [{'code': 'INVALID_TOKEN', 'description': 'Unauthorized', 'id': '0', 'field': None}]

The child logger in this case was the ApiClient class. This is helpful information to include in bug reports/issues.

Debug & Info
2025-01-01 16:35:31,697 - Patcher.Analyzer - DEBUG - Attempting to filter titles by FilterCriteria.OLDEST_LEAST_COMPLETE.
2025-01-01 16:35:31,704 - Patcher.Analyzer - INFO - Filtered 5 PatchTitles successfully based on FilterCriteria.OLDEST_LEAST_COMPLETE

Potential Solutions#

When encountering an issue, it is beneficial to separate environment issues (API credentials, network timeouts, etc.) versus configuration issues with Patcher (bug, property list issue, etc.).

Update Patcher#

Ensure you are running the latest version of Patcher before proceeding. This is the least invasive and most straightforward method of resolving issues relating to Patcher:

$ python3 -m pip install --upgrade patcherctl

Full Reset#

To rule out configuration issues with Patcher, perform a full reset. This will automatically trigger the setup process to run. If the issue persists after performing a full reset, proceed to reinstall Patcher.

Known Issue

During the setup process, if an API Role or Client already exists for Patcher, the Jamf API will return a 401 response. It is recommended to retrieve the API credentials from keychain before performing the full reset, and proceeding with the SSO setup type. Alternatively, the API client and role can be removed from Jamf before performing the full reset if the standard setup type is preferred.

Reinstalling Patcher#

As Patcher is distributed via PyPI, pip can be leveraged to uninstall and reinstall Patcher:

$ python3 -m pip uninstall patcherctl

A prompt will show asking for confirmation to proceed. Enter Y to confirm uninstallation.

Found existing installation: patcherctl <version>
Uninstalling patcherctl-<version>:
  Would remove:
    /Library/Frameworks/Python.framework/Versions/3.12/bin/patcherctl
    /Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/patcher/*
    /Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/patcherctl-<version>.dist-info/*
Proceed (Y/n)?

Optional

Before reinstalling Patcher, remove all contents from Patcher’s Application Support directory except the logs directory. The logs should be kept to assist in troubleshooting the issue(s). The directory can be found at the following path: ~/Library/Application Support/Patcher/.

Reinstall Patcher with python3 -m pip install patcherctl. For detailed instructions, see our install page.

Resources#

If you’re still running into issues with Patcher, there are a couple of ways to get in touch.

1. Submit an Issue#

Submitting an issue on our GitHub repository is likely the quickest way to get support. Include as many details as possible, including what troubleshooting steps have already been taken to resolve the problem. Be sure to fill out as many fields on the issue form as able. We will do our best to get to the issue as quickly as we are able to.

2. Reach out on the MacAdmins Slack#

Despite having full-time jobs, we try to stay as active as possible on the MacAdmins Slack. Find us in the #patcher channel by clicking the banner at the top of the page. For other details on how to contribute, see our contributing page.