Solving Finder tag problems

Finder tags are a popular way to add accessible metadata to files and folders in macOS, with attractive properties:

Their associated colour tags are easily seen and instantly recognisable.
Each colour can be associated with one or more text labels.
The Finder can display tagged items conveniently.
Tags propagate through iCloud Drive, and can be used fully in iOS and iPadOS.
Tags are generally preserved within macOS, for example when copying or moving items between volumes.
Tags are searchable using Spotlight, as their text labels are indexed.

I have explained their use in this article.

Their principle limitation is that they’re limited to 7 colours, together with no colour. That allows you to assign multiple text labels to each colour, but the results of that can be confusing given that Finder display and search are based on their text labels not colours.

Implementation

Finder tags are implemented as extended attributes (xattr), currently of type com.apple.metadata:_kMDItemUserTags. However, historically they can also be implemented alongside other Finder information in com.apple.FinderInfo xattrs.

com.apple.metadata:_kMDItemUserTags xattrs consist of a binary property list containing brief UTF-8 text. This is an NSArray consisting of Strings, each containing a text label, followed by the newline character, followed by the colour number (0-7). The array can be empty. Obviously, labels can’t include the newline character; although they can include the colon character :, that has been reported as causing problems in some versions of macOS and is worth avoiding.

Colour numbers used are:

none, 0
grey, 1
green, 2
purple, 3
blue, 4
yellow, 5
red, 6
orange, 7.

Thus a tag name might read Redn6, or Orangen7 Greenn2 for two colours, where n represents the newline character 0a.

When the Finder writes a tag xattr to an item, it also adds a null com.apple.FinderInfo xattr of 32 bytes length, if a xattr of that type isn’t already present.

com.apple.FinderInfo xattrs can be used to store a single colour tag without a text label, although this shouldn’t be encountered any more. When they do, a single byte is set in their fixed length of 32 bytes, the kColor flag just to the right of the Hide extension flag. For instance, <00000000 00000000 00040000 00000000 00000000 00000000 00000000 00000000> sets the Green tag. This scheme uses a different encoding for colour flag values:

none = 00, 01
grey = 02, 03
green = 04, 05
purple = 06, 07
blue = 08, 09
yellow = 0A, 0B
red = 0C, 0D
orange = 0E, 0F.

Basic checks

With a selection of tagged items, first verify the colours and text labels are shown correctly in the Finder’s Get Info dialog, and match those against com.apple.metadata:_kMDItemUserTags xattrs inspected using xattred‘s drag and drop interface. Also check com.apple.FinderInfo xattrs, although they shouldn’t have their kColor flag set.

Check tagged items both locally and in iCloud Drive. Note that tags should be preserved even when that file has been evicted from local storage to iCloud, as xattrs are stored locally and retained on dataless files. Tags should also be displayed in apps that support them, and in File Open and Save dialogs.

Problems with these basic checks should make you suspect file system errors in volumes affected. Run Disk Utility’s First Aid on that volume and perform necessary repairs. Although they should be shown in some other file systems, Finder tags are best-supported by HFS+ and APFS volumes and may have limitations in other file systems.

iCloud Drive syncing

Test this with:

In the Finder, open a user folder in iCloud Drive. Select a file there, and add a Finder tag to it using the contextual menu.
That should result in an immediate and brief sync up to iCloud, to copy that tag up.
Check that this change syncs across other Macs and devices connected to the same Apple Account.
If necessary, add the tag at a known clock time and use that to inspect iCloud systems in the log, using Mints or Cirrus.

Failure to sync the changed tag information with iCloud indicates a problem in syncing with iCloud, and requires separate diagnosis.

Spotlight search

Before looking at search for tags, first confirm normal Spotlight indexing and search function using Mints. If those tests don’t work correctly for search of file contents, address those problems first before assessing tags.

The single most common reason for search failures is that the item being searched for is in a location excluded either from indexing or from returning search results. Check Spotlight or Siri & Spotlight settings for the following:

That item’s category isn’t excluded from appearing in Spotlight search results. For example, if the Images item in the list there isn’t ticked, then images will still be indexed, but Spotlight won’t return any images in its search results. Unless you have a good reason, the simplest setting here is for all boxes to be ticked.
That item’s path isn’t within any of the locations listed in Search Privacy…, as those aren’t indexed at all.

There have been additional methods for excluding specific items from being indexed by Spotlight, of which two are currently effective:

appending the extension .noindex to the folder name (this previously worked using .no_index instead);
making the folder invisible to the Finder by prefixing a dot ‘.’ to its name;
putting an empty file named .metadata_never_index inside the folder; that no longer works in recent macOS.

Check that the items you expect Spotlight to find aren’t subject to any of those. Details of those items not synced by iCloud Drive are given in this article.

In addition to those excluded locations, Sequoia (and possibly other recent versions of macOS) generally excludes folders and files within either of the two user-writable Library folders, /Library and ~/Library. Limited indexing is performed within the Application Support folder, but that doesn’t appear to include tags. Although iCloud Drive as a whole is shown as being inside ~/Library, it’s indexed differently, as given above, and that should also include app-specific folders in iCloud Drive.

Before even considering rebuilding a volume’s Spotlight indexes, check whether Spotlight correctly indexes test files created using Mints, when you add tags to them. When tags are added, you may be able to see a short burst of mdworker activity in Activity Monitor, and it should be recorded in the log, as checked using Mints. Full details of diagnosing and fixing problems with Spotlight search are given in this article.

Step summary

Verify tags as xattrs both locally and in iCloud Drive, using xattred.
Verify syncing in iCloud Drive using Mints or Cirrus.
Check Spotlight search is working correctly for other contents, using Mints.
Verify tagged items are in a path that isn’t excluded from indexing, and their category is set to return search results, in System Settings.
Diagnose any underlying Spotlight problems using Mints.