An icon that renders in an admin screen but is missing from the Icon block is not necessarily broken. Check whether its registration marks it non-public before changing REST permissions or copying the SVG into every post.
Understand the visibility boundary
The Gutenberg change tracked in pull request 82634 allows registered icons with public:false to remain available to server-side wp_get_icon() while excluding them from REST discovery. The implementation distinguishes icon manifest behavior from runtime registration, so inspect the layer your integration actually uses. Do not infer support solely from a version number in a tutorial; confirm the installed code.
This setting is a publishing boundary, not a safe place to store secrets. An icon drawn into a page can still be viewed by a reader. Never embed credentials or private customer details in SVG markup.
Make a four-part inventory
Record the collection slug, icon name, registration owner and intended audience. Then make four separate observations: whether registration runs, whether the server helper resolves the icon, whether the REST response exposes it, and whether an existing public page draws it. Keep the browser console error separate from an HTTP status code.
On staging, use one deliberately public test icon and one deliberately non-public icon. Give them different names. Do not change a production collection to public simply to see whether a picker becomes populated.
Public fixture: Discoverable as intended. Private fixture: Excluded as intended. Older content: Saved references still work. Roles: No elevated access workaround. Explanatory checklist, not a customer test result.
Follow the result, not the missing thumbnail
| Result |
Likely boundary to inspect |
| Neither test icon resolves server-side |
Registration hook, loading or names |
| Public icon appears, private one does not |
Visibility may be working as intended |
| REST lists the public icon but the picker is empty |
Editor request, search or cached state |
| Public page loses a previously used icon |
Content dependency on a changed registration |
If your test reveals duplicate collection identifiers, use our icon collection collision audit. Renaming a collection can also break saved references, so inventory content before doing it.
Repair the correct owner
For a decorative public-content icon, register a supported public resource with a stable identifier. For an admin-only icon, leave the visibility boundary intact and use the supported rendering path inside your own interface. For an accidental identifier change, restore compatibility or migrate references with a reviewed mapping, rather than broadly exposing unrelated collections.
Check one older post, one new post and one reusable pattern after the repair. A picker that works only for new content does not prove that historical references survived. Also test an editor role that lacks administrator capabilities; the solution must not require elevated access just to render allowed content.
Evidence for a useful bug report
Include exact builds, registration code stripped of unrelated business logic, the expected icon identifier, the REST status and a small content example. Identify whether the result is expected exclusion, missing registration or an editor-only display problem. Avoid attaching full site exports when a two-icon fixture reproduces it.
HandL WP can investigate an icon or editor problem without changing access rules blindly.
Primary source: Gutenberg private icon implementation. These are proposed verification steps, not measured results from a customer installation.
References reviewed October 17, 2026. Examples are explanatory, not customer test results.