faq: turd files and heudiconv

other/faq.rst

@@ -37,3 +37,29 @@ character ``-`` was a UTF-8 special character instead. Just delete it and
 replace the character with an actual hyphen and your script should
 automatically become an ascii file.
 
+
+heudiconv/bids: UnicodeDecodeError
+------------------------
+
+When running Heudiconv, Apple users sometimes notice an error similar to this:
+
+.. code-block:: python
+
+      File "/src/heudiconv/heudiconv/bids.py", line 77, in populate_bids_templates
+        populate_aggregated_jsons(path)
+      File "/src/heudiconv/heudiconv/bids.py", line 109, in populate_aggregated_jsons
+        json_ = load_json(fpath)
+      File "/src/heudiconv/heudiconv/utils.py", line 182, in load_json
+        data = json.load(fp)
+      File "/opt/miniconda-latest/lib/python3.6/json/__init__.py", line 296, in load
+        return loads(fp.read(),
+      File "/opt/miniconda-latest/lib/python3.6/codecs.py", line 321, in decode
+        (result, consumed) = self._buffer_decode(data, self.errors, final)
+    UnicodeDecodeError: 'utf-8' codec can't decode byte 0xb0 in position 37: invalid start byte
+
+Usually this indicates that Heudiconv tried to load json files that are in fact
+`._` binary files created by `Apple's Finder
+<https://apple.stackexchange.com/a/14981>`_. It seems that there is no way to
+avoid their creation and you will have to clean them manually. Other
+workarounds are setting your BIDS folder read-only before loading them in Finder or
+avoiding Finder altogether.