Why is ~/Documents a symlink to itself, and how should this be fixed?

I'm a programmer diagnosing a customer's issue with our software. We're having some problems writing into the user's Documents folder in macOS Mojave 10.14.6.*

It turns out that the customer's ~/Documents folder is a symlink to itself, causing ELOOP errors when calling file APIs, and a Too many levels of symbolic links error when attempting to view its contents in the Terminal with the ls command.

Terminal output

However, in the Finder, the folder displays normally, and appears to contain 15GB of contents.

enter image description here

The first time we saw this issue I wrote it off as an unsolved mystery, but this is the second customer we have seen in the past few years with a Documents folder that is a symbolic link to itself.

So my questions are:

  1. How is this possible?
  2. What can cause this configuration? Is there any legitimate reason it might be configured this way?
  3. Is it safe to tell the user just to move all the contents somewhere safe, delete the folder, and then recreate it in the Finder?

* The path is obtained by passing NSDocumentDirectory into NSSearchPathForDirectoriesInDomain.


Solution 1:

How is this possible?

It's easy to mess up when using ln on the command line. A symlink to self is legal (though nonsensical) so you wouldn't get an error when creating it.

What can cause this configuration? Is there any legitimate reason it might be configured this way?

It's useless and should be removed. Once removed, they can create a new ~/Documents/ folder. If you're concerned about safety, keep in mind you can always drag things back from the trash.

Is it safe to tell the user just to move all the contents somewhere safe, delete the folder, and then recreate it in the Finder?

If it's a symlink to self then it has no contents, because it's just a self-referential symlink. It's not a folder, it's just a recursive symlink. Finder is showing some folder that's named Documents but that doesn't mean it's showing ~/Documents/. You could create a folder with that name anywhere and add it to the Finder sidebar.

It would probably help to ask the user to cmd-click on the folder name at the top of the Finder window. That will show where it's located:

Finder "Documents" window showing full folder path