Fixing Apple Calendar sync problems on MacOs, a tale of caching gone wrong

Ever seen an error message like this before?

Apple Calendar for MacOs sync error
Apple Calendar for MacOs sync error

If so, could you figure out, as a regular user, what was wrong?

Well, I have run into the problem. In fact many times in the past, I usually ignored it, would close Calendar app and not rely on it. But recently, I thought I’d look into it. I found out why and how to fix it. My first place of call was Google Search, leading to StackOverflow, some Apple articles, all quite frankly misleading, but they put me on the path to a solution.

Such error would turn off every user who isn’t technical, and the fix is likewise a turn-off. Here is how to fix this problem. I assume that the readers might not all be experienced Mac users or very technical, hence I include more detailed steps.

1.- Quit Calendar, to prevent it from crashing. Simply close the app, sometimes it gets stubborn and you have to force-quit it.

2.- Stop Calendar Agent service, it runs in the background. Here is how.

  • Start the Activity Monitor app. I always use ⌘ + Space to find and start programs. Press ⌘ + Space, type Activity Monitor then ENTER.
  • Search for: CalendarAgent, just start typing the word. when it’s highlighted, click on the Force Quit button as indicated. See the illustration. activity monitor

3.- Now it’s time to open Terminal.

Press ⌘ + Space, type Terminal then ENTER, to start the app. Be cautious in this step, don’t accidentally delete anything. If in doubt, simply move files to your Desktop for example. First, let’s see what files are there by listing them

$ ls -lpatrh ~/Library/Calendars/

You’ll see something like this:

list-of-cached-calendar-files

This is macOS caching calendar events, locally on my MacbookPro. Some of these folders contain files that are no longer valid. Apparently, Calendar app wasn’t able to figure it out and is throwing its hands in confusion. With some patience I could go through these folders, find out exactly which ones aren’t good and remove them. But, no, I don’t have time for that. I just get rid of them all and let Calendar re-sync with the servers. In my example, I move the files to Downloads, which can be emptied if everything goes well.

$ mv ~/Library/Calendars/* ~/Downloads/

Now that the cached files are gone, it’s time to start Calendar app again.

4.- Optionally, toggle Calendar OFF then back ON

Since I am unsure how many other places caching may be occurring, I apply my usual macOs toggle technique. This means that I turn OFF and then ON again, the Calendar feature of my Internet Accounts. To be sure, press ⌘ + Space, type Internet Accounts then ENTER. toggle calendar

5.- Open Calendar app again

When Calendar starts up now, it should find that it needs to download everything from the servers, it would do so, and the error should be gone for good. Phew! What a hassle that was!

This shouldn’t happen, yet it does. This is not user friendly in many ways. For a start, the problem seemingly appeared out of nowhere, in the sense that I am not aware of any user action I specifically took that should result in such outcome. This means that 99% of regular users would find this baffling at best. Second, the error message means nothing because, again, I never entered such a URL anywhere while setting up my Mac. I can see what it is suggesting. It was all auto-magic while configuring my email accounts, so I shouldn’t be asked to fix a URL that I never actually typed.

What was the problem then?

In short, it was a caching problem. The clue can be seen in the suggested buttons. Here it is:

revert to server

This is telling me that a local copy, hence a cache, is not aligned with the server somehow. Looking at the URL, I can’t see anything wrong and all my other devices, iPhone and iPad (Android or others, if that’s what you have), are functioning properly. In earlier attempts, I did what it suggested, the dialog would pop up again and again. I also tried the ignore option on occasions, to the same effect, the dialog keeps popping up. As a user this is very confusing, because you don’t know how many times it would and why it keeps nagging about it – my hunch at this point, is that the dialog would occur for each problematic folder found in the Calendars cache place. Worse, after a reboot and sometimes a re-logon, the same ugly dialog pops up again, repeatedly. This is infuriating, as a user, it seems I can’t get this issue behind. If this happens to you, hopefully with the steps above you have resolved it.

I’ve had Calendar working properly many times and over very long stretches without any troubles. So I knew Calendar app can be reliable, I just don’t know what tripped it up and what else I might be missing should I continue ignoring the error. That is what motivated me to look into it eventually.

Summary

One might ask, how would Apple ever allow such a seemingly trivial problem to occur? Why not prevent it by design? I can see a large number of reasoning behind it, why it might not be so easy to solve this kind of problem in a durable way. For example, when a local copy of a calendar event isn’t aligned with the server, it may be because changes on one device didn’t make it to the server or other devices yet. With many devices on the go, determining which one has the fully complete overview might not be a trivial task. People would be furious if they should lose data due to some clever sync algorithms. I could dive into this subject at length, but that wouldn’t fit in this post.

Caching is very handy when it works. Apple uses it profusely, everywhere and in many ways. But when it breaks, lots of time can be lost trying to diagnose and fix it. I don’t have any stats, but caching could be the cause of a proportionally large number of headaches that we routinely face with our computing devices. In this instance, especially for Apple products, it’s really hard to find out what may be going on.

Since Apple doesn’t tell us much about the inner-workings of their software products, a user, however savvy, may not have much clue how to address this kind of problem. This situation causes a lot of the frustration amongst users of Apple products, and particularly the technically savvy ones. I don’t have a clearcut answer. It’s easy to guess that the very large majority of Apple users aren’t technically savvy, hence wouldn’t venture trying to fix technical issues. However, a case could be made to include an Expert Mode, for those who feel like having a go. Maybe include an Insane Mode (borrowing from Tesla), for the really daring folks, even if that would mean voiding warranty or some sort of disclaimer. We should be able to tinker with our toys if we feel like it, there is no need for father-figure for the entire community.

Interesting thoughts: Frameworks are fundamentally broken

I just read this blog post, Frameworks are fundamentally broken. Many of the points highlighted resonated with me. Then I realised that I blogged about an aspect of the problem that can occur with frameworks. It was a few years back, in fact in 2010 as I just verified. I kept my post at a high level, taking the discussion above Rails and other particular paradigms but focusing on the cognitive load aspect alone.

Tim’s article calls for reflexion. My own take on the issue was triggered as I spotted a rant on Rails (of Ruby on Rails). My post is Code frameworks and ghettos, where creativity gets a lock-in