Troubleshooting.

Mail Shepherd 3.0 (build 454) · Updated October 21, 2026

Mail Shepherd stops rather than guess. A problem from something you did, or from an Auto-Sweep, shows as an orange warning icon on the page: point at it to read the problem, or click it to open the Action Log, whose Problems Only menu lists them all. Most problems come from a setting that’s off on Setup, or from Mail’s window being in a state Delete can’t use. If nothing here helps, use Send Support Log… on Get Support.

Setup

A required setting is off. Open Setup, find the row with the red icon, and follow the steps under its button.

“Allow Mail Shepherd in System Settings → Privacy & Security → Accessibility, then try again.”

Accessibility is off, or macOS lost it (this can happen after an update). Click Open Settings in Setup’s Accessibility row. If Mail Shepherd is already listed and on, select it, click −, then click + and add it again.

“Mail access is off. In System Settings → Privacy & Security → Automation, allow Mail Shepherd to control Mail, then try again.”

Click Open Settings in Setup’s Mail Automation row and turn on Mail under Mail Shepherd.

“Mail’s blocked list couldn’t be read, so Mail Shepherd can’t tell which senders are blocked. Nothing in Mail was changed.”

Mail Shepherd needs Full Disk Access to read Mail’s blocked list. Click Open Settings in Setup’s Mail’s Blocked List row and turn on Mail Shepherd (if it isn’t listed, click + and add it from Applications).

“Mail’s blocked list is in a format Mail Shepherd doesn’t recognize, so Sweep can’t safely tell which senders are blocked. Nothing in Mail was changed.”

macOS keeps Mail’s blocked list in a format Apple doesn’t document. If a macOS update changes it, Mail Shepherd still finds what addresses it can, so Review Blocked and Blocked Senders show them, but Sweep and Auto-Sweep don’t run until Mail Shepherd is updated. Please send your support log from Get Support so we can fix it quickly.

“Sweep needs Contacts access, so mail from your contacts is never treated as junk or blocked by a domain. Nothing in Mail was changed.”

Contacts access is off. Click Allow or Open Settings in Setup’s Contacts row. The same fix applies to “This page requires access to Contacts.” on Blocked Domains and Allowed Domains, and to “Mail Shepherd can’t read Contacts (turn it on in Setup)”.

“Couldn’t read Contacts (…), so mail from your contacts can’t be told apart. Nothing in Mail was changed.”

Access is on, but Contacts didn’t answer. Try again in a moment. If it keeps happening, open the Contacts app to check that it loads, then send the support log.

macOS refused the change. Check System Settings → General → Login Items, where you can also add or remove Mail Shepherd yourself.

Sweep and Auto-Sweep

Sweep is dimmed

A Sweep needs Mail open (the page says “Open Mail to run a Sweep.” with Open Mail), Mail’s blocked list and Contacts access, and nothing else running. Check the notices on the Sweep page and the rows on Setup.

“Mailbox changed while Mail Shepherd was checking it. Nothing in it was changed. Try again after Mail finishes syncing.”

Something changed in that mailbox while Mail Shepherd was reading it, for example new mail arrived or Mail was still syncing. “Mail changed while Mail Shepherd was reading it” means the same. Wait until Mail settles, then run a Sweep again.

“Mail returned an incomplete answer. Check Mail before trying again.”, or Action Log entries that start with “Unconfirmed:”

Mail didn’t confirm some changes, so Mail Shepherd stopped. Look at the messages named in the Action Log in Mail, then run a Sweep again; it only changes what still needs changing.

“3 messages from blocked domains couldn’t be handled.”

The Blocked Domains step couldn’t move some messages. The Action Log has each one and why. The next Sweep tries again.

Auto-Sweep didn’t run

Auto-Sweep runs only while Mail Shepherd is open, and skips a turn when Mail isn’t open, Mail’s blocked list can’t be read or Contacts access is off. When a Sweep is due it also waits until Mail Shepherd is idle: nothing running, no dialog open, the Sweep, Automate or a Review list showing, and 20 seconds without clicks or typing. See Automate.

Deleting

Only Delete Selected and Delete Permanently use Mail’s window. They need Mail open with its main message window, and nothing else clicked or typed while they run.

“Open Mail and its main message window, then try again.”

Mail is closed, or only a message or Settings window is open. Open Mail’s main window (Window → Message Viewer in Mail).

“Mail’s message list isn’t available. Open its main message window and try again.”

Mail’s main window is closed, or Mail is still loading. Open it, wait until it settles, then try again.

“Close the dialog attached to Mail’s message window, then try again.”

A sheet or alert is open in Mail. Close it, then try again.

“Mail’s main message window isn’t in front. Nothing was deleted.”

Another window came in front during a delete. Try again without switching apps.

“Mail’s Accessibility interface didn’t respond.”

Bring Mail forward and try again. If it keeps happening, turn Mail Shepherd off and on again in Accessibility settings.

“Mail’s Delete isn’t available right now. Nothing was deleted.”, “Mail didn’t accept Delete. Nothing was deleted.” or “Couldn’t find Edit → Delete in Mail.”

Mail couldn’t delete the selection just then. Click in Mail’s message list once, come back, and try again.

“The selection in Mail changed before Delete.” or “Mail didn’t remove it after Delete.”

A message wasn’t one Mail Shepherd could safely delete, or Mail didn’t confirm it. Click Refresh, check the message in Mail, and try again if it’s still listed.

“Couldn’t return Mail’s window to the Inbox.”

The delete finished, but Mail’s window wasn’t put back on the Inbox. Click your Inbox in Mail.

“Mail Shepherd was busy, so nothing was changed. Try again.”

Something else was running, such as a Sweep. Wait for it to finish, then try again.

“Stopped. What was done before Stop is in the Action Log.”

You clicked Stop (or pressed ⌘.). Anything finished before then stays done.

Review pages and lists

“Open Mail to see the messages to review.”

The Review pages read Junk and Trash from Mail, and Mail Shepherd never opens Mail for them. Open Mail, then click Refresh.

“This list appears when the current work finishes.”

A Sweep or another action is running. The list is read as soon as it’s done.

A message I expected isn’t on Review Junk

If its sender or domain is blocked, it’s on Review Blocked instead. Mail from your contacts and Allowed Domains is never listed. A message in Trash is listed only while Mail has it marked junk; the Action Log notes any message Mail didn’t keep marked junk when a Sweep moved it.

Block Sender or a Block Domain button is dimmed

Point at it to see why: the sender or domain is already blocked, the domain is a shared provider or service (block the sender instead), Contacts access is off, or Mail Shepherd is busy.

“Couldn’t read Mail’s blocked list: …” on Blocked Domains, or a banner on Blocked Senders

See Mail’s Blocked List on Setup, then click Try Again.

“Stopped. Click Refresh to read again.”

You stopped the first read of a domain list. Click Refresh.

Open Mail’s Blocked List… didn’t show the Blocked list

Mail Shepherd needs Accessibility to go straight to it. Otherwise, in Mail, choose Mail → Settings… → Junk Mail → Blocked.

“Couldn’t save Blocked Senders: …”, or “Problem saving a list” in the Action Log

A list couldn’t be saved on this Mac, so the change didn’t happen. Try again; if it keeps happening, send the support log.

Other

“There’s no action log to send yet. Run a Sweep first.”

Send Support Log needs an Action Log. Run a Sweep, then send it, or use Email Support….

“Part of Mail Shepherd is missing. Reinstall Mail Shepherd.”

Download and install Mail Shepherd again from your tester link.

“Couldn’t check for updates”

take66.ai couldn’t be reached. Check your internet connection and try Mail Shepherd → Check for Updates… again later.

“Problem: Mail Shepherd crashed” in the Action Log

Mail Shepherd crashed earlier, and macOS’s crash report is in that entry. Please send the support log so we can fix it.

Was this page helpful? Tell us.