Custom icons for shortcuts not working: what to check, in order

The instructions were followed and the icon did not change. Or it changed, and a week later the old one is back. This class of problem has several unrelated causes, and trying fixes in the order they occur to you turns into guesswork. Sorting the symptom first narrows it to one of three groups, and from there the check that finds the cause is usually two or three steps down the list.

Sort the symptom into one of three groups

Before touching anything, decide which of these is happening.

The first group is the operation being refused. Paste is greyed out, or the click does nothing, or the image will not go in at all. This is a problem with the gesture or with permissions.

The second group is the operation succeeding but the display not agreeing. Finder shows the new artwork, the Dock shows the old one. Or everything looks stale everywhere. This is a problem with cached display, or with the operation having silently not landed.

The third group is the change not lasting. It worked, then reverted, and repeating the steps produces the same outcome again. This is a problem with where the artwork was stored, and no amount of redoing the steps carefully will fix it.

The reason this sort matters is that the third group looks like the first two from the outside. People in the third group redo the paste, watch it work, and conclude the problem is solved, then find it back a fortnight later. If the artwork has already reverted once, skip to the section on storage rather than repeating the steps.

When the operation is refused, check where you clicked

A greyed out Paste in the Get Info window has a documented cause, and it catches almost everyone at least once.

If Edit > Paste isn't available, you may have clicked the large icon below Preview. Source: support.apple.com

The Get Info window shows the artwork twice. There is a small one at the top, just under the title bar, and a large one inside the Preview section. Only the small one accepts a replacement. Clicking the large one leaves Paste dimmed, and nothing about the window explains why.

If the small one is selected and Paste is still unavailable, the next suspect is the clipboard. Copying an image file in Finder puts a file on the clipboard, not an image. Apple's steps are specific about this: open the image file in Preview first, then use Edit and Copy from the menu bar. The gesture looks identical and the result is not.

If both of those check out, the target itself may not accept a custom icon. The same page notes that the Home folder can be customized but the folders that come with macOS cannot, naming Applications, Library, System, and Users. Beyond that list, an item on a read-only volume or one that is locked will refuse in the same silent way. The Get Info window shows your privileges near the bottom, and if it says read only, that is the answer.

When the display disagrees, find out which surface is stale

If the operation went through but the picture is wrong, the question is whether one surface is stale or all of them are.

The Dock is the usual offender. A Dock tile holds information captured when the item was added, so changing the original later does not always propagate. The fix is to remove the tile and add it again. Nothing needs rebuilding, and making new artwork at this point wastes the work.

The app switcher or search results showing old artwork while Finder shows new artwork has the same shape: a display surface holding its own copy. Relaunching Finder clears most of these. Hold Option and use the Apple menu, or open the force quit window, select Finder, and relaunch. Open apps are unaffected.

If every surface shows the old artwork, the operation did not land, and the previous section is where to go. There is a quick way to confirm this. Select the item, open Get Info, click the small icon under the title bar, and choose Cut. If a custom icon was ever applied, this removes it and the original returns, which proves the paste had worked. If nothing visibly changes, nothing was ever applied.

When the picture looks wrong rather than absent

Blurry edges and unreadable tiles are not malfunctions. They are the source image being the wrong size for where it is being displayed.

Artwork renders small in the Dock and considerably larger in Finder icon view at a big size, or in Quick Look. Checking only the Dock and declaring success is how soft artwork gets shipped. After replacing an icon, look at it wherever it renders largest.

The most common source problem is a favicon. Browser tab artwork is often around 32 pixels, and scaling that up to fill a large tile produces a smeared result no sharpening can recover, because the detail was never there. Many services publish brand assets at proper sizes, and locating that page is faster than fighting an upscaled favicon.

The opposite failure shows up at the small end. At 16 pixels an image with too many elements turns into a smudge of color. One or two characters is the ceiling for text, thin strokes need thickening, and a photograph reduced to that size reads as nothing at all. Artwork that survives both extremes is the only kind worth attaching.

When it reverts, the storage location is the cause

This is the most frequently reported version and the one that does not respond to careful technique.

Artwork pasted through Get Info is stored as metadata attached to the item. When an app updates, the old item is replaced by a new one, and the new one arrives without that metadata. The original artwork returns. For anything on a monthly release cadence, that means a monthly repaste, which nobody sustains. Check whether the interval between reverts matches the app's update interval, because if it does, the cause is settled.

Sites installed through a Chromium browser change for a different reason. The artwork is whatever the site publishes, and the site can publish something new. Chrome's help describes a notification offering to accept the update, ignore it, or uninstall the app. Ignoring holds the current look, at the price of a prompt every time the service rebrands.

Safari web apps behave differently again. The app holds its own icon setting, reachable by opening the web app, clicking its name in the menu bar, and choosing Settings. Artwork set there is not subject to the site's decisions.

One more cause worth ruling out: items stored inside a synced folder can have older state written back from another machine, which overwrites a local change. If the same revert is happening across two machines, that is the line to pull.

Symptoms that look related but are not

A few problems get filed under icon trouble and then resist every check above, because the cause sits somewhere else entirely.

The name changing while the artwork does not is the most common of these. Renaming and icon replacement run through different mechanisms, so a successful rename proves nothing about whether the icon operation landed. Treating the rename as evidence that the gesture worked sends the diagnosis down the wrong branch.

Two apps made from the same site, where only one accepts a new icon, usually means the two were made by different routes. One was added through a browser and the other had artwork pasted onto an existing item, which is easy to do weeks apart and then forget. Different routes store artwork in different places, so the same gesture does not produce the same result. Establish how each one was created before comparing them.

A missing red badge on a Dock tile also gets reported as an icon fault. It is a separate feature showing unread notification counts, and Apple's documentation notes that the notification permission has to be answered inside the web app rather than in the browser for the badge to work. No amount of attention to the artwork will make it appear.

Finally, restarting the whole machine is the fix people reach for when the first three checks fail, and it rarely helps. Relaunching Finder addresses stale display, and nothing about a full restart touches metadata that was never written or artwork owned by a website.

Confirming that the fix actually held

A fix that looks applied is not the same as a fix that survived, and the difference only shows up later. Two checks close that gap.

The first is immediate and takes seconds. After applying artwork, look at it in three places rather than one: the Dock, Finder at a large icon size, and the app switcher. Agreement across all three means the artwork landed on the item rather than on a single display surface. Disagreement means going back to the section on stale surfaces before doing anything else.

The second check has to wait. For anything that updates on a schedule, the real test is whether the artwork is still correct after the next update installs. Note the date it was applied, and look again after the app has updated once. Artwork that survives one update cycle will survive the rest, and artwork that does not was never going to, regardless of how carefully it was applied.

Skipping the second check is how the reverting problem gets discovered weeks later, usually at the moment the tile is needed. Fifteen seconds of looking after an update turns a recurring annoyance into a decision made once.

When several items lose their artwork at the same time

A single reverted icon and a whole row of them are different problems, and the second one is diagnosed by the timing rather than by any check on an individual item.

Three events produce a mass revert. Restoring from a backup brings back the items as they were stored, and any artwork applied after that backup was taken is gone with it. Migrating to a different Mac carries over files but not always the metadata attached to them, so a set of carefully customised items arrives looking factory fresh. A macOS upgrade occasionally has the same effect on items sitting in system managed locations, though this is far less common than the first two.

The useful question is what happened on the machine that day. If the artwork disappeared on the morning after a migration, no per item check will explain it, and there is nothing to repair on any single icon. The items are not broken; the layer that held the pictures was not carried across.

Recovery depends on where the source images are. This is the point at which people discover that the artwork was pasted from images that were downloaded once, used, and never kept. Rebuilding then means sourcing every image again, which is usually several times more work than the original job. Keeping the source images in one folder, named to match the items they belong to, turns a mass revert from an afternoon into ten minutes.

The same event is also the clearest signal that the approach itself is worth changing. Artwork applied as metadata is only as durable as the metadata, and metadata is exactly what backups, migrations, and updates treat as optional. Artwork that lives inside the app travels with the app, because there is no separate layer to lose. A reader who has now rebuilt the same set twice has enough evidence to stop treating each revert as an incident.

One practical step helps regardless of route. Keep a short list of which items have custom artwork and where each image came from. Five lines in a note is enough. When something resets, the list turns an investigation into a sequence of known steps, and it also answers the question that comes up during the next machine change, which is whether any of these items were customised at all.

When to stop troubleshooting and change route

Two failed reattachments is enough. The cause is where the artwork lives, not how it was applied, and a third attempt produces the same result.

Switching route is worth it when any of the following is true. The artwork reverts on every update and the item is used daily. The same fix has been redone more than once in a month. There are five or more items on the list.

In those cases, artwork stored inside the app removes the failure mode entirely, since nothing external can replace it. Tools that turn sites into standalone Mac apps are built around that arrangement, and the supported services list shows which services already come with name, URL, and artwork registered together, meaning the sourcing step never happens in the first place.

For one or two items that never update, hand work is still cheaper than switching. The overhead of changing approach exceeds the occasional repaste. Write down the items, note which ones update on a schedule, and let that column decide.

What to change first

Classify the symptom before doing anything else: refused operation, stale display, or reverted artwork. The first two are fixed by the checks above, in order, and usually within a few minutes. The third is not a technique problem, so stop repeating the steps and pick a different place for the artwork to live. What can be set per app is covered in the features overview, the steps are in the guide, and Kagemusha is one of the tools whose documented behavior around updates addresses the reverting case directly.