Added warning message and paragraph about replacements/max length interaction in documentation.

beets/library.py

@@ -795,8 +795,14 @@ class Item(LibModel):
             # When zero, try to determine from filesystem.
             maxlen = util.max_filename_length(self._db.directory)
 
-        subpath = util.legalize_path(subpath, self._db.replacements, maxlen,
-                                     os.path.splitext(self.path)[1], fragment)
+        subpath, fellback = util.legalize_path(
+            subpath, self._db.replacements, maxlen,
+            os.path.splitext(self.path)[1], fragment
+        )
+
+        # Print an error message if legalize fell back to default replacements
+        if fellback:
+            log.warning(u'fell back to default replacements when naming file')
 
         if fragment:
             return subpath

beets/util/__init__.py

@@ -597,7 +597,9 @@ def legalize_path(path, replacements, length, extension, fragment):
             first_stage_path, None, length, extension, fragment
         )
 
-    return second_stage_path
+        return second_stage_path, True
+    else:
+        return second_stage_path, False
 
 
 def str2bool(value):

docs/reference/config.rst

@@ -119,6 +119,11 @@ compatibility with Windows-influenced network filesystems like Samba).
 Trailing dots and trailing whitespace, which can cause problems on Windows
 clients, are also removed.
 
+When replacements other than the defaults are used, it is possible that they
+will increase the length of the path. In the scenario where this leads to a
+conflict with the maximum filename length, the default replacements will be
+used to resolve the conflict and beets will display a warning.
+
 Note that paths might contain special characters such as typographical
 quotes (``“”``). With the configuration above, those will not be
 replaced as they don't match the typewriter quote (``"``). To also strip these