justin․searls․co

How to fix Contacts not syncing in macOS

There are all sorts of little ways Apple's services can stop working correctly if you ever change the primary email address on your Apple Account. Here's one I ran into. A few months ago, one of my Macs stopped getting new iCloud contacts. My other devices kept syncing just fine. It turns out the Mac still had my old email address in its iCloud Contacts settings, even though System Settings showed the new one.

Here's how I fixed it on macOS 27.2.1 without signing out of iCloud.

How to verify you have the same problem

  1. Check that a missing contact shows up on another device and in Contacts on iCloud.com. Make sure iCloud Contacts is enabled on the Mac. Apple's troubleshooting steps are a good place to start

  2. Open Console and look for AddressBookSourceSync. My logs showed Failed to get a X-mobile me token, HTTP 401, and NSURLErrorDomain Code=-1012. One failed request to *-contacts.icloud.com had my old email address in the URL. Josh Long saw the same thing

  3. If you want to check the account records directly, run the query below in Terminal. On my machine, the AppleAccount row had my current address and both CardDAV rows had the old one

    /usr/bin/sqlite3 -readonly "$HOME/Library/Accounts/Accounts4.sqlite" <<'SQL'
    SELECT t.ZIDENTIFIER, a.ZUSERNAME
    FROM ZACCOUNT a
    JOIN ZACCOUNTTYPE t ON a.ZACCOUNTTYPE = t.Z_PK
    WHERE a.ZACCOUNTDESCRIPTION = 'iCloud'
      AND a.ZACTIVE = 1
      AND t.ZIDENTIFIER IN ('com.apple.account.AppleAccount', 'com.apple.account.CardDAV');
    SQL
    

How I fixed it

Signing out of iCloud and back in worked for Josh and some people on Reddit and MacRumors. I wanted to stay signed in, so I had Codex make a much smaller change. This involves editing macOS's private Internet Accounts database, so only try it if the query shows the same mismatch.

  1. Quit Contacts. If you're using an agent to do this for you, give it temporary Full Disk Access
  2. Use SQLite's backup API to make a private backup of ~/Library/Accounts/Accounts4.sqlite. Check that the backup opens and passes PRAGMA quick_check. Test the edit on a copy first
  3. Update ZACCOUNT.ZUSERNAME for the two active iCloud com.apple.account.CardDAV records linked to your Apple Account. Check ZACCOUNTPROPERTY for those same records. On my Mac, the old address was also in the archived userName, AccountURL, HomeInfo, and PrincipalInfo/principalInfo properties. Decode those binary plists, replace the old address in the relevant strings (including the URL-encoded form), and re-encode them. Apply the changes together in one SQLite transaction
  4. Run launchctl kickstart "gui/$(id -u)/com.apple.AddressBook.SourceSync" and reopen Contacts. Once the sync ran, my missing contact showed up and the logs showed iCloud accepting the requests. Check for a contact you knew was missing, and you'll have verified the fix

I miss the days when I believed the lie that Macs were unlike Windows PCs because they didn't inevitably get bogged down with cruft like this shit, but it is indeed a lie. I wish Apple were more committed to preventing and remediating the kind of data corruption that occurs over time with each of their devices (and backups of those devices, and iCloud databases…). But, at least we have now have coding agents to do what Apple don't.


Got a taste for hot, fresh takes?

Then you're in luck, because you'll pay $0 for my 2¢ when you subscribe to my work, whether via RSS or your favorite social network.

I also have a sporadic newsletter where I write high-tempo, thought-provoking essays about life, in case that's more your speed:

And if you'd rather give your eyes a rest and your ears a workout, might I suggest my long-form solo podcast, Breaking Change? Odds are, you haven't heard anything quite like it.