macOS Contacts.app sync appears completely broken

[kiler129]

Please excuse the title, but I really had no idea what to make of the behavior I observed. This potentially may be multiple issues.

My environment

• Radicale: v3.5.4
• Running method: Docker on macOS, started with docker run -p 8443:5232 -v "$PWD/config:/etc/radicale" -v "$PWD/data:/var/lib/radicale" grepular/radicale:3
• Configuration: (attached full config directory; htpasswd password is test123)

  [server]
  max_connections = 15
  ssl = True
  certificate = /etc/radicale/server_cert.pem
  key = /etc/radicale/server_key.pem
  [encoding]
  [auth]
  type = htpasswd
  lc_username = True
  strip_domain = False
  htpasswd_cache = False
  htpasswd_filename = /etc/radicale/htpasswd
  [rights]
  [storage]
  skip_broken_item = False
  [web]
  [logging]
  level = debug
  bad_put_request_content = True
  backtrace_on_debug = True
  request_header_on_debug = True
  request_content_on_debug = True
  response_content_on_debug = True
  rights_rule_doesnt_match_on_debug = True
  storage_cache_actions_on_debug = True
  [headers]
  [hook]
  [reporting]
  

1st attempt - macOS + empty server (failure)

Upon starting the server with empty data/ directory it created a boilerplate structure:

data
├── .cache
│   └── rosetta
└── collections
    ├── collection-root
    │   └── greg
    └── .Radicale.lock

I added the server to macOS Calendar, with information as on the screenshot below, and changed its name upon adding:

Attempting to add a contact produced nothing on the server. However, digging through macOS logs I found:

Nothing worked until I manually created a data/collections/collection-root/greg/default-addressbook/.Radicale.props with {"tag": "VADDRESSBOOK"}. I wonder if this has something to do with shenanigans from 12 years ago in #32 where No main address book in homeInfo was also reported and fixed? ;)

To not pollute the logs I only attempted to add a single contact. Later on I played a bit after adding the prop file and it was somewhat working, but the sync was.... spotty and sometimes required re-editing the contact to get it to sync. However, the biggest problem - and where a bug for sure exists - is adding a second address book redirects all requests to a new-empty address book. macOS doesn't seem to grasp a concept of >1 address book on the server somehow and it will default to the newest one created on the server. Magic :)

Debug attached:

• macos_empty_data.log

2nd attempt - iOS (success)

I next attempted to start the server with a data directory populated with pure VCFs + .Radicale.props across two address books. I attached this as clean-data.tgz.

Next, upon starting the server, I added the server to iPhone:

All contacts synced perfectly. Adding a new one was instantaneously reflected on the server. iPhone doesn't seem to have any issues seeing multiple address books nor user-editable groups:

Deug attached:

• iphone_add.log
• clean-data.tgz (i.e. before starting server)
• data-after-iphone.tgz (i.e. after all operations on iOS)

3rd attempt - macOS + seed data (failure?)

I seed the data directory with the same clean-data.tgz file from the 2nd attempt and started the server.

Contact's app showed me only one of the address books with a single contact:

While adding one worked, I cannot access the other address books and I'm sure adding another empty one on the server will again switch/lock me in the new empty one.

Debug attached:

• macos_add.log
• data-after-macos.tgz

Help? :)

I honestly don't even know where to start debugging it. I read through the whole v3 docs and I don't see any obvious misconfiguration on my end. I also looked at RFC-6352, as I'm very familiar with HTTP and somewhat with WebDAV, but I don't see anything immediately obvious in the logs that would violate the protocol.

[kiler129]

Digging through extensive (and containing a lot of personal information) macOS logs, I found something peculiar. macOS sees the account as having two home collections ... one with principal url of /greg/ and second with /greg/another-book/. There's no mention of /greg/default-addressbook/. I'm not sure if some of the magic redirects Redicale does may not be breaking the autodiscovery.

        HomeInfo =         {
            "/greg/" =             {
                GuardianRestricted = 0;
                path = "/greg/";
                privileges =                 (
                    "DAV::all",
                    "DAV::read",
                    "DAV::write",
                    "DAV::write-content",
                    "DAV::write-properties"
                );
                resourceTypes =                 (
                    "DAV::collection",
                    "DAV::principal"
                );
                supportedReports =                 (
                    "DAV::expand-property",
                    "DAV::principal-property-search",
                    "DAV::principal-search-property-set"
                );
                url = "https://greg@<serverIP>:8443/greg/";
            };
            "/greg/another-book/" =             {
                GuardianRestricted = 0;
                displayName = "Another Addressbook";
                path = "/greg/another-book/";
                privileges =                 (
                    "DAV::all",
                    "DAV::read",
                    "DAV::write",
                    "DAV::write-content",
                    "DAV::write-properties"
                );
                resourceTypes =                 (
                    "DAV::collection",
                    "urn:ietf:params:xml:ns:carddav:addressbook"
                );
                supportedReports =                 (
                    "DAV::expand-property",
                    "DAV::principal-property-search",
                    "DAV::principal-search-property-set",
                    "DAV::sync-collection",
                    "urn:ietf:params:xml:ns:carddav:addressbook-multiget",
                    "urn:ietf:params:xml:ns:carddav:addressbook-query"
                );
                url = "https://greg@<serverIP>:8443/greg/another-book/";
            };
        };
#....
        PrincipalInfo =         {
            "DAV::principal-URL" = "https://greg@<serverIP>:8443/greg/";
            "urn:ietf:params:xml:ns:carddav:addressbook-home-set" =             (
                "https://greg@<serverIP>:8443/greg/"
            );
        };

---

This is most likely macOS bug....

Edit: While testing a sabre-io/Baikal, I did even more analysis as having 3 servers causing very similar problem points at macOS being buggy. I wrote a pretty extensive analysis in a comment at sabre-io/Baikal#1191 (comment). However, the TL;DR is:

• macOS randomly doesn't sync. That's it, it will just silently lose changes upon Contacts.app close.
• Using more than one address book does not work on macOS
  • One should not try as this leads to contacts landing in "random" one.
  • This may be a regression, as it was seemingly broken in 10.6/Snow Leopard and fixed in 10.10/Yosemite
  • iCloud Contacts, while utilizing CardDAV, don't suport multiple address books. They use groups/lists instead.
• The best course of action whoule be to probably add a very big warning in docs.

[ar-rm]

Hi,

Thank you for all of the time you took investigating this, thoroughly documenting, and posting about it.

I've been running into a few of these Radicale + Contacts.app (macOS) issues for a while and this post really helped solve them. Specifically the realization that you have to stick to a single AddressBook if you want Contacts.app to see the addresses stored in Radicale.

I found some additional details that might help you or others.

---

How Contacts.app chooses which AddressBook to read

"macOS doesn't seem to grasp a concept of >1 address book on the server somehow and it will default to the newest one created on the server. Magic :)"

[...]

Using more than one address book does not work on macOS
One should not try as this leads to contacts landing in "random" one.

I think I found the underlying rule. It's not random:

Calendar.app chooses based on the ID of the AddressBook, picking the one that comes first in alpha numeric (numbers first) order.*

(*Or as Radical labels it in its Web UI: HREF.)

0->10..., then A->Z. So if you have two AddressBooks, the one whose ID starts with 0 will appear in Contacts.app and *not the one that starts with A**.

You can even see this affect Contacts.app in real-time:

1. Add a new AddressBook (via the Radicale Web UI) that has an ID ("HREF") lower than all of the others (ie: Starts with "000"). (More on how to do this below.)

2. Wait a few seconds/minutes* for Contacts.app to refresh from the server.

RESULT: Your contacts have disappeared!

3. Delete that AddressBook and wait for the refresh again.

RESULT: Your contacts are back!

(**No great pattern here. I tend to find a contact card that's on the server, edit it a few times, and click the "Edit/Done" buttons a few times. Eventually it calls out to the server.)

Setting a specific AddressBook ID:

By default, Radicale sets a new AddressBook's ID to a random UUID. (This might be where you deduced that the pattern is random.)

You have no control over this ID if you create it from within Contacts.app or any other client app.

But if you create the AddressBook via the Radicale Web UI, you can set the ID ("HREF") to whatever you'd like!

• You can either slightly modify the UUID to start with a 0, or set it to some user-friendly name.
• The the <input> for "HREF" in the Web UI enforces some sane character limits (lowercase, no spaces, no special characters).

---

Slight digression: If you use have multiple AddressBooks, create them via the Radicale Web UI

As you pointed out, more than one AddressBook is bad for Contacts.app. So probably don't do that.

BUT if you do want to create a new one (for some reason), you should almost certainly do it via the Radicale Web UI so you can control what the ID will be. If you don't (ie: You create it from within Contacts.app or BusyContacts) the random UUID that Radicale generates could start with a number that's lower than your current preferred default AddressBook. As a result, suddenly, all of your contacts would disappear from Contacts.app!

Bad times.

I stumbled on one possible use for an AddressBook that macOS can't read:

If you have some cards that you want to store in Radicale but don't want all of the various systems services (that read from AddressBook-v22.abcddb-wal) to have access, you can create an AddressBook like: "Exclude from macOS".

Any cards in their will be invisible to Contacts.app but visible to another client like BusyContacts.app.

---

iOS Contacts.app > macOS Contacts.app

"iPhone doesn't seem to have any issues seeing multiple address books nor user-editable groups:"

I noticed that too.

The only difficulty in the UI of the iOS version Contacts.app is, AddressBooks and Groups/Lists/Tags are co-mingled. There is no visual distinction between them.

---

Speaking of Tags

Part of why I went down this rabbit hole was because I wanted to switch to BusyContacts.app to avoid some of the problems that come with Contacts.app and because it has a few more features. It was also helpful to be able to use another app while looking into this. But it also exposed other issues.

"Tags" in BusyContacts.app are the equivalent of "Lists" in Contacts.app.

This is the way to go if you want to have the same contact in multiple groupings.

On Radicale's end, a Tag is just another .vcf file with some special properties:

X-ADDRESSBOOKSERVER-KIND:group
X-ADDRESSBOOKSERVER-MEMBER:urn:uuid:a2622ds9-45ef-476b-2caa-6bb54e3c6e07
X-ADDRESSBOOKSERVER-MEMBER:urn:uuid:30E1AC4E-DBD8-3B27-922F-D074A20C3560

If you use BusyContacts, make sure to Enable the setting: Map Tags to Groups

• https://www.busymac.com/docs/busycontacts/47214-tags-groups/
• https://www.busymac.com/docs/busycontacts/47214-tags-groups/#troubleshooting

In my testing so far, everything related to Tags/Lists seems to work bi-directionally between Contacts.app and BusyContacts.app. IOW: Radicale and BusyContacts.app seem to play well together, but I don't know how much I trust Contacts.app.

---

The best course of action whoule be to probably add a very big warning in docs.

Agreed. And link to this discussion :-)

Next up for me: Switching to Radicale for calendars and seeing if Calendar.app and/or BusyCal give me headaches too 🤦🏻.

Thank you again for your posts!

[ar-rm]

I found and worked through some other issues that you (or others) may have run into as well.

But I didn't want to post about them here because they're a little off topic. (They're related more specifically to data loss when exporting cards from Contacts.app, the AddressBook-v22.abcddb file, and some tools to help.)

I figured it would be ok to post some links for cross-referencing (breadcrumbs) though:

• Contacts.app skipping (or creating empty files for) some contacts on vCard export
• Michael Tsai - Blog - Contacts.app Skipping Export of Some Contacts
• relikd/abcddb2vcard: Convert abcddb AddressBook format to vCard. Export profile images from vCard.

[tinohendricks]

I think I have a slightly different problem with the macOS Contacts.app but it seems related so I'm posting here.
I try to setup a simple shared address book following the different hints found here.

collections-root
|---- adrshare
  |---- bd4d9863-b9e5-8599-7e44-7d9db713bffb
|---- user1
  |---- bd4d9863-b9e5-8599-7e44-7d9db713bffb (symlink)
|---- user2
  |---- bd4d9863-b9e5-8599-7e44-7d9db713bffb (symlink

Rights:

[adrshare]
user: .+
collection: adrshare/[^/]+
permissions: rw

user1 accesses the (empty) address book first, successfully creates one card:

[2025-07-25 12:31:00 +0200] [1960/Thread-45 (process_request_thread)] [DEBUG] 'user1' has write access to collection with tag 'user1/bd4d9863-b9e5-8599-7e44-7d9db713bffb'

But as soon as any other user tries to access the address book an exception occurs:

[2025-07-25 12:32:21 +0200] [1960/Thread-56 (process_request_thread)] [DEBUG] 'user2' has write access to collection with tag 'user2/bd4d9863-b9e5-8599-7e44-7d9db713bffb'
[2025-07-25 12:32:21 +0200] [1960/Thread-56 (process_request_thread)] [DEBUG] 'user2' has write access to item 'b150c7c2-dd84-4d3a-8f25-668ebbb2a597.vcf' from 'user2/bd4d9863-b9e5-8599-7e44-7d9db713bffb'
[2025-07-25 12:32:23 +0200] [1960/Thread-57 (process_request_thread)] [ERROR] An exception occurred during REPORT request on '/user2/bd4d9863-b9e5-8599-7e44-7d9db713bffb/': vevent_list

Any ideas what the exception could be?

Thanks!

[pbiering]

[ERROR] An exception occurred during REPORT request on '/user2/.../': vevent_list - > which version are you using? 3.5.5.dev is still unstable, and this should not occur on 3.5.4 imho

[tennysontbardwell]

I'm having issues getting MacOS's Contacts App to add a radicale v3 server. I get a successful login server-side and Unable to verify account name or password. client-side. I am able to successfully configure iOS.

It seems like the vibe is "Contacts is fickle and some level of broken," so I suppose my results aren't that surprising to the folks here and I shouldn't spend more time on this?

As an aside, since radicale is a WebDAV server, it's not responsible for broken clients like MacOS's Contacts---but I still feel a bit sad that it wasn't mentioned in the docs. (Although the absence of MacOS/iOS was glaring, and I assumed that support was experimental at best)

[ar-rm]

Yes, Contacts.app on macOS (and "Internet Accounts" in "System Settings.app") seem to be fickle when interacting with Radicale. Especially establishing the initial connection.

But once you get the account setup right, it seems to work fairly reliably.

Here's how I got it to work:

Contacts.app > Settings > Accounts > Server Settings:

• Server address: computer-name.local
  • Your computer's Local hostname, set in System Settings > Sharing > Local hostname.
  • Notice: Do NOT add the port number here.
• Server path: Empty (the placeholder value is: /principal/user/, but should not be what's actually used)
• Port: 5232 ✔ Use SSL

I remember setting the username/password both in Contacts.app and System Settings.app > Internet Accounts. It was as if sometimes it worked when I set it in one but not the other.

Radicale config file:

(only including what seems relevant)

ssl = True
certificate = ./certs/server_cert--radicale_certificate.pem
key = ./certs/server_key--radicale_certificate.pem

[auth]
type = htpasswd
htpasswd_filename = ./users

htpasswd_encryption = bcrypt

[logging]
# This could help with debugging
level = warning

SSL was annoying to get right. I don't remember how I did it right now. There are other threads about that:

• Setup Radicale to work with SSL - IOS12 · Issue #879 · Kozea/Radicale
• [ERROR] An exception occurred during request: SSL handshake failed: EOF occurred in violation of protocol (_ssl.c:749) · Issue #1183 · Kozea/Radicale
• wanting to use a signed certificate with ssl · Issue #367 · Kozea/Radicale
• How to implement SSL · Issue #945 · Kozea/Radicale

If you need more help with that, let me know and I'll look through my notes.

[tennysontbardwell]

Interesting. I was using a remote sever with a letsencrypt certificate, but I radicale was hosted on port 443 and under the path /radicale (nginx proxy). I might open up port 5232 and let radicale manage the ssl at some point in the future. Perhaps this info is helpful to someone else in the future.

[tennysontbardwell]

I'm still having trouble even when radicale is hosted at the root (although nginx provides the ssl in my setup, I could try to avoid that if it seemed like it might help). I'll post my setup, in case it's helpful context. I'm comfortable with the IP address leakage of client + server here:

Nginx config: link

Radicale v3 config:

[storage]
filesystem_folder = ./var/

[server]
max_connections = 20
max_content_length = 100000000
timeout = 30

[auth]
delay = 1
type = htpasswd
htpasswd_filename = ./users
htpasswd_encryption = plain

Logs

[2025-09-23 14:06:47 +0000] [2325469/Thread-26 (process_request_thread)] [INFO] Successful login: 'tennyson' (htpasswd)
[2025-09-23 14:06:47 +0000] [2325469/Thread-26 (process_request_thread)] [INFO] REPORT response status for '/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/' with depth '1' in 0.083 seconds: 207 Multi-Status
[2025-09-23 14:06:52 +0000] [2325469/Thread-27 (process_request_thread)] [INFO] PROPFIND request for '/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/' with depth '0' received from 127.0.0.1 (forwarded for '128.62.43.129,128.62.43.129') using 'macOS/15.6.1 (24G90) AddressBookCore/2695.500.71'
[2025-09-23 14:06:52 +0000] [2325469/Thread-27 (process_request_thread)] [INFO] Access to '/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/' denied for anonymous user
[2025-09-23 14:06:52 +0000] [2325469/Thread-27 (process_request_thread)] [INFO] PROPFIND response status for '/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/' with depth '0' in 0.001 seconds: 401 Unauthorized
[2025-09-23 14:06:52 +0000] [2325469/Thread-28 (process_request_thread)] [INFO] PROPFIND request for '/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/' with depth '0' received from 127.0.0.1 (forwarded for '128.62.43.129,128.62.43.129') using 'macOS/15.6.1 (24G90) AddressBookCore/2695.500.71'
[2025-09-23 14:06:52 +0000] [2325469/Thread-28 (process_request_thread)] [INFO] Successful login: 'tennyson' (htpasswd)
[2025-09-23 14:06:52 +0000] [2325469/Thread-28 (process_request_thread)] [INFO] PROPFIND response status for '/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/' with depth '0' in 0.004 seconds: 207 Multi-Status
[2025-09-23 14:06:52 +0000] [2325469/Thread-29 (process_request_thread)] [INFO] OPTIONS request for '/tennyson/' received from 127.0.0.1 (forwarded for '128.62.43.129,128.62.43.129') using 'macOS/15.6.1 (24G90) AddressBookCore/2695.500.71'
[2025-09-23 14:06:52 +0000] [2325469/Thread-29 (process_request_thread)] [INFO] OPTIONS response status for '/tennyson/' in 0.001 seconds: 200 OK

[jhoogeboom]

I have the same problem, did serving Radicale from /radicale , so not from root, work?

[pbiering]

The log shows successful login Successful login: 'tennyson' (htpasswd)

[tennysontbardwell]

Yes. This might have been buried in the thread by this point:

I'm having issues getting MacOS's Contacts App to add a radicale v3 server. I get a successful login server-side and Unable to verify account name or password. client-side.

It is definitely very strange, and does not obviously feel like radicale's fault.

[ar-rm]

I think I remember having issues when I saw (in stderror) the username + UUID in the path like these:

/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/

It's as if the failure is occurring because Contact.app is trying to read from an AddressBook UUID that doesn't exist or Radicale isn't accepting such an explicit path. (These are just guesses.)

Maybe try appending the explicit username only part to either:

Server address: pan.tennysontbardwell.com/tennyson/
Server path:/tennyson/

(I realize this is different than what I wrote above but also: "fickle" :-)

You also might want to try deleting that AddressBook (from the Radical Web Interface) in case it's corrupted and that's what's throwing Contacts.app.

Then again, this line specifically makes me think it could be something completely different:

[2025-09-23 14:06:52 +0000] [2325469/Thread-27 (process_request_thread)] [INFO] Access to '/tennyson/b6dad9f5-1332-408b-89ee-7658cac2533b/' denied for anonymous user