Skip to content

Logs and Troubleshooting

Jump to bottom
Gil Burns edited this page Jul 18, 2026 · 11 revisions

Logs and Troubleshooting

Log Files

All log files are written to /Library/Logs/Patcher/.

    FileName     Written By Contents
Patcher_General_<YYYY-MM-DD>.log patcher Scan, check, stage, apply activity
Patcher_Updates_<YYYY-MM-DD>.log patcher Installomator Label updates
scheduler_stderr.log LaunchDaemon Unexpected stderr / crash output from patcherscheduler

Enable verbose logging for more detail:

sudo defaults write /Library/Preferences/com.gilburns.patcher LogVerbose -bool true

Or via MDM:

<key>LogVerbose</key>
<true/>

Verbose mode logs every label evaluation, version comparison, and file I/O operation. It generates significant output during a scan. Turn it off in production once your issue is resolved.

Viewing Logs

# Follow patcher activity in real time
tail -f /Library/Logs/Patcher/Patcher_General_<YYYY-MM-DD>.log

# Follow update of Installomator label files
tail -f /Library/Logs/Patcher/Patcher_Updates_<YYYY-MM-DD>.log

# View recent LaunchDaemon error output (Hopefully there are none)
cat /Library/Logs/Patcher/scheduler_stderr.log

Common Issues

Labels are never downloaded / "No labels version found"

Symptom: patcherscheduler.log shows "no labels version" or all phases are skipped.

Causes and fixes:

  1. No network access to GitHub — check firewall rules for api.github.com and raw.githubusercontent.com.
  2. InstallomatorLabelsDisable: true and no Managed Labels present — add managed labels or disable the key.
  3. The labels folder exists but is empty — delete /Library/Application Support/Patcher/Installomator/ and let the scheduler re-download.

Scan finds no apps

Symptom: Discovered/ folder is empty or contains far fewer apps than expected.

Causes and fixes:

  1. IgnoredLabels pattern is too broad — review the pattern (wildcards apply).
  2. Apps are installed in home folders and IgnoreAppsInHomeFolder: true — either move apps to /Applications or set ConvertAppsInHomeFolder: true.
  3. Apps installed in unusual paths — add a Managed Label with the correct targetDir.
  4. Run patcher scan manually with LogVerbose enabled to see why each label was skipped.

An app is always shown as "unknown version"

Symptom: patcherreport broken lists the label, or the label shows version "" in labelDetail.

Causes and fixes:

  1. The label uses appCustomVersion but the function fails silently — test the label in isolation.
  2. The app is not installed in any standard path — check targetDir in the label.
  3. Set IgnoreUnknownVersionLabels: true to skip these labels entirely.

An update is downloaded every stage cycle (version mismatch loop)

Symptom: patcher.log shows the same installer being downloaded and discarded repeatedly.

Cause: The label reports a newer appNewVersion that doesn't match the installed version after the update is applied (e.g. Spotify shows a promotional build version).

Fix: This is handled automatically by VersionMismatchThrottleDays. If you see it happening frequently, check whether the label's appNewVersion logic is accurate, or increase the throttle duration.

swiftDialog prompts don't appear

Symptom: Users are not prompted even though blocking processes are running.

Causes and fixes:

  1. swiftDialog not installed — run sudo /usr/local/bin/tpp/patcher ensure.
  2. SwiftDialogEnabled: false — check your configuration profile.
  3. The daemon runs as root but cannot reach the user's session — verify SessionCreate: true in the LaunchDaemon plist.
  4. The hard deadline has passed — no prompt is shown after DeadlineDaysHard.

Daemon is not running

# Check status
sudo launchctl print system/com.gilburns.patcher.scheduler

If the daemon is not loaded:

sudo launchctl bootstrap system /Library/LaunchDaemons/com.gilburns.patcher.scheduler.plist

If it was loaded but crashed, check scheduler_stderr.log:

cat /Library/Logs/Patcher/scheduler_stderr.log

Manually triggering a phase for testing

# Force an immediate run of all due phases
sudo launchctl kickstart system/com.gilburns.patcher.scheduler

# Run a specific phase directly (bypasses interval checks)
sudo /usr/local/bin/tpp/patcher scan
sudo /usr/local/bin/tpp/patcher check
sudo /usr/local/bin/tpp/patcher stage
sudo /usr/local/bin/tpp/patcher apply

Data Directory Reference

/Library/Application Support/Patcher/
├── Cache/
├── Config/
│   └── config.json          ← scheduler state (last run times, label version)
├── Discovered/
│   └── <label>.plist        ← per-app metadata; delete to force re-scan of one app
├── Installomator/
│   ├── Labels/              ← downloaded label files; delete folder to force re-download
│   └── Version.txt
└── Managed/
    ├── Labels/
    └── Version.txt

Deleting a specific Discovered/<label>.plist forces that label to be re-scanned on the next scan cycle. Deleting Config/config.json resets all phase timers, causing all phases to run on the next scheduler wake.

Clone this wiki locally