Troubleshooting.

Mail Shepherd 3.0 for the Mac App Store (build 535) · Updated October 24, 2026

Mail Shepherd stops rather than guess. A problem from something you did, or from an Auto-Sweep, shows as an orange warning triangle beside the button or setting: point at it to read the problem, or click it to open the Action Log, whose Problems Only menu lists them all. Each Sweep’s own log is on Sweep Logs. If nothing here helps, write to us from Get Support; an Action Log entry’s Copy button copies everything we need.

Accounts and signing in

“iCloud didn’t accept that address and password. Check that the whole password was pasted, or click Create App Password… to make a new one.”

Mail Shepherd signs in with an app-specific password, not your Apple Account password. On Settings, click … beside the account, click Create App Password…, make a new password at account.apple.com, paste all of it, then click Test Connection and Save. Changing your Apple Account password, or revoking the app-specific password, makes Apple refuse the old one.

“That doesn’t look like an app-specific password: Apple’s have 16 letters, like abcd-efgh-ijkl-mnop.”

Part of the password is missing, or something else was pasted. Copy it again from Apple’s page.

Point at the triangle in the Accounts list to read why. “The app-specific password is missing from this Mac’s keychain. Click … and paste a new one.” means just that. After any other sign-in problem, fix the password and click Test. “Not tested yet. Click Test.” only asks you to check a new account.

“skipped until it signs in again”

Auto-Sweep stops using an account when iCloud refuses its password, because signing in again and again with a refused password could lock it. Fix the password, then click Test or run a Sweep yourself. A Test that fails for another reason, such as no network, shows a triangle on the account but doesn’t stop Auto-Sweep from trying it.

“Couldn’t reach iCloud Mail (imap.mail.me.com): …” or “iCloud Mail didn’t answer. Check your internet connection and try again.”

The network is down or slow, or something such as a VPN or firewall blocks the connection. Mail Shepherd gives up on a step that takes too long instead of waiting forever; what was done before is in the Action Log. Try again once you’re connected. After the Mac wakes, Mail Shepherd waits for the network before signing in.

“iCloud Mail gave an unexpected answer: …” or “iCloud Mail doesn’t support …, so nothing was changed.”

iCloud answered in a way Mail Shepherd didn’t expect, so it changed nothing. Try again later; if it keeps happening, write to us with the Action Log entry.

“There’s no account to sweep. Add one in Settings.” or “No account could be used: … Fix it in Settings.”

Add an account on Settings, or fix the one named. “The chosen account is no longer in Settings.” means the account menu still pointed at a removed account: choose another.

Contacts

“Your contacts haven’t been read yet (see the Contacts page). Nothing was changed: mail from your contacts must never be treated as junk.”

A Sweep reads your contacts first, and doesn’t run until at least one account’s contacts have been read. Open Contacts, click Refresh, and check the Contacts Refresh Log at the bottom of the page.

“…: skipped, its contacts couldn’t be read from iCloud (see the Contacts page).”

A Sweep and the Review pages leave out an account whose contacts couldn’t be read, so mail from people you know is never treated as junk there; your other accounts still run. The Contacts Refresh Log says why that account’s contacts couldn’t be read.

“iCloud Contacts didn’t accept … and its app-specific password.”

Contacts sign in with the Apple Account’s own email address. If the account in Settings uses a different address, such as an alias, its contacts can’t be read yet. Otherwise, make a new app-specific password as above.

“Read your contacts first (Contacts page → Refresh), so mail from people you know never shows as junk.” or “This page needs your contacts: click Refresh on the Contacts page.”

The Review pages, Blocked Domains and Allowed Domains wait for your contacts. Click Refresh on Contacts.

“Couldn’t read the hashing key from this Mac’s keychain (…). Nothing changed.”

Your contacts are kept as hashes made with a key in this Mac’s keychain. macOS didn’t hand it over. Try again; if it keeps happening, restart your Mac, and write to us if that doesn’t help.

Mail’s Blocked Sender List

The status says “Not Linked”

Mail Shepherd reads Mail’s list only after you link it. On Settings, click Link…; the file dialog opens with Mail’s file selected, so just click Link.

“That’s a copy of Mail’s list (…), not Mail’s own, so it wasn’t linked. Link the one in Library › Preferences.”

Only Mail’s own file can be linked, because a copy wouldn’t change when you block someone in Mail. Click Link… again and leave the selected file as it is.

“Mail’s blocked senders file couldn’t be read, so the senders read before are kept.”

The file was damaged or still being written. Nothing is lost; it’s read again before the next Sweep.

“Mail’s Blocked Sender List: Mail Shepherd can’t find it anymore. Unlink it and click Link… again in Settings.”

Click Unlink…, then Link…, on Settings.

Sweep

Sweep is dimmed

There’s no account yet, or Mail Shepherd is busy with something else. Point at Sweep to see which.

“3 changes weren’t confirmed by the server.”, or Action Log entries that start with “Unconfirmed:”

iCloud didn’t confirm those changes, so they aren’t counted. Run a Sweep again; it changes only what still needs changing. A move iCloud accepted but couldn’t be asked about afterwards counts as moved, with a note in the Action Log.

“no Junk mailbox on the server, so it was skipped” or “Junk was skipped: there’s no Trash mailbox to move junk to.”

That account has no mailbox marked as Junk or Trash on iCloud. Check the account’s mailboxes in Mail or at icloud.com, then run a Sweep again. Delete Selected and Delete Permanently also need Trash.

“This account stopped partway” or “This account was skipped.”

The account named ran into the problem shown; the other accounts were still swept. What was changed before is in the Action Log.

“The server didn’t accept junk marks (…); messages are still moved.”

Messages were moved, but without the junk mark. Nothing needs doing.

“Stopped by user”, “Stopped because the Mac went to sleep” or “Stopped because you switched users”

Stop (⌘.), sleep and switching users end a Sweep after the current step; the display sleeping doesn’t. What was done before stays done. Run it again.

A contact’s message stayed in Junk

A message from a contact or an Allowed Domain leaves Junk only if iCloud authenticated it and it passes all four spoof checks. Otherwise it’s counted as Kept in Junk and listed on Review Junk, where its details say why. Use Move to Inbox there if it’s genuine.

Auto-Sweep

Auto-Sweep didn’t run

Auto-Sweep runs only while Mail Shepherd is open. When it’s due, it waits until Mail Shepherd has been idle for 20 seconds, nothing else is running, no dialog is open, and Sweep, Automate or a Review list is showing (not a message’s details); Automate then says “Next when Mail Shepherd is idle”. A turn that comes during a Sweep, or soon after one, is skipped, since that Sweep counts. After the Mac wakes it waits a minute. Recent Changes lists only Auto-Sweeps that changed something; every one is on Sweep Logs. See Automate.

Review pages

The list is empty and says “Loading…”

Junk and Trash are being read. Click Stop (⌘.) to stop; “Stopped before Junk and Trash were read. Click Refresh to read them.” then stays until you do.

“The chosen account’s password is missing. Update it in Settings → Accounts.” or “Not everything could be read: …”

Fix the account named on Settings, 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.

“2 of the selected messages weren’t deleted.”

Before deleting, Mail Shepherd reads each message again and acts only if it’s still there as listed and still belongs on the page. The reason follows, for example “Junk changed on the server since the list was read, so nothing in it was changed. Refresh and try again.” or “… no longer belongs on Review Junk.” Click Refresh and try again if it’s still listed. “The Action Log couldn’t be written, so nothing was deleted.” means a delete is never made without being logged first.

A Block button is dimmed

The note beside it says why: “Already blocked”, “Blocked by parent domain”, or a shared email provider, mailing service or hosting service, which can’t be blocked as a domain (block the sender instead).

“This message has no Message-ID, so Mail can’t be asked to show it.”

Open in Mail finds a message by its Message-ID. Search for it in Mail instead.

“Mail Shepherd was busy, so nothing was changed. Try again.” or “Stopped. What was done before Stop is in the Action Log.”

Wait for the work running to finish, then try again. Anything finished before Stop stays done.

Lists and settings

“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.

“… couldn’t be read … A copy of the file was kept as ….unreadable-….json.”

One of your lists (Blocked Senders, Blocked Domains or Allowed Domains) was damaged. Mail Shepherd kept what it could read and saved a copy of the damaged file beside it, so nothing is overwritten. Check the list, and write to us with the Action Log entry.

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

Other

“Couldn’t check for updates”

Only in the version from the Take66 website: 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. Click it, click Copy, and send it to us from Get Support.

Was this page helpful? Tell us.