Help & support
Answers to the most common questions about using Headicons, what it can and cannot do, and what to expect from each result.
Getting started
Headicons is a stateless diagnostic tool for site icons. You supply a URL. The tool
reads the page's <head>, collects every declared icon — every
<link rel="icon">, apple-touch-icon, and
shortcut icon — fetches each file, parses the real pixel dimensions from
the binary headers, and reports what it found.
It also checks /favicon.ico and /apple-touch-icon.png at the
site root even when they are not declared, because browsers and iOS request those paths
by convention. A blank browser tab can be caused by the root fallback 404ing just as
often as by a missing declaration.
To use it: go to the App page, paste a public URL into the input field, and click "Check". Results appear as a table showing each icon's declared vs actual dimensions, and a summary of which consumer (browser, iOS home screen, search result) has an icon to use.
Frequently asked questions
There are several reasons a reachable icon can appear missing:
- — Site is behind Cloudflare. The Workers runtime cannot open a socket back into its own network. A site hosted behind Cloudflare that is itself checked against Cloudflare will show all icons as missing. This is a known Workers limitation.
-
—
The icon path is case-sensitive. A server may serve
/favicon.icobut return 404 for/Favicon.ico. Headicons uses the exact path from the page declaration. If a declaration sayshref="Favicon.ico"but the file is only atfavicon.ico, the file is genuinely missing at the declared path. - — The server blocks programmatic fetch. Some hosting configurations return a 403 or a CAPTCHA page to non-browser requests. Headicons reports these as missing because the file is not served to a raw HTTP request.
Before concluding the tool is wrong, try fetching the exact URL it tested with
curl -I <icon-url> from a different machine.
No. Headicons has no accounts, no sign-in, no API keys. Paste a URL, read the results. Nothing is saved between visits.
No. The tool is stateless. Each check fetches the page and icons in real time. No check history, no URL logs, no user data is persisted on the server. Close the tab — the result is gone.
Planned Pro features (saved history, scheduled monitoring) would change this, but they are not yet built.
There is no single correct answer — it depends on which browsers and devices you target. The most common setup that covers most consumers includes:
-
—
A
favicon.icoat the site root (at least 32×32 pixels with multiple ICO frames, or a separate 48×48 PNG) — used by legacy browsers and the browser tab on most desktops -
—
An
apple-touch-iconlink (180×180 PNG) — used by iOS Safari for home-screen bookmarks -
—
An
<link rel="icon">withtype="image/svg+xml"pointing to an SVG — used by modern browsers supporting scalable favicons (Chrome, Firefox, Edge)
Headicons does not generate or design icons — it only tells you which of the files you have declared are actually reachable and the right size.
/favicon.ico and /apple-touch-icon.png even when I never declared them?Browsers do this. Chrome, Firefox and Safari will request /favicon.ico from the root path regardless of what your page declares. iOS Safari does the same for /apple-touch-icon.png. If neither file exists at the root and you have not declared an alternative, the browser gets a 404 and shows a blank or generic placeholder icon.
Headicons checks these paths precisely so you can catch the case where a page declares everything correctly but shows nothing because the root fallback is missing.
No. Headicons runs server-side and can only fetch publicly accessible URLs. A check of http://localhost, http://127.0.0.1, http://10.* or any private IP range will fail — the tool has no access to your local network or development server.
It means the icon file was fetched successfully, but the binary format does not match what the <link> declaration claims. For example, a <link rel="icon" type="image/png"> that serves a WebP file, or an apple-touch-icon declaration that points to a JPEG. Some browsers handle mismatches gracefully; others ignore the file entirely.
Known limitations
The Workers runtime that powers Headicons cannot open an HTTP connection back into its own Cloudflare network. Any site hosted behind Cloudflare and checked through Headicons will report all icon files as missing, even when they are present. This is a documented platform limitation. There is no workaround in the current architecture.
The tool can only check public URLs. Private IP ranges (localhost, 10.x, 172.16–172.31, 192.168.x), internal hostnames, and development servers are unreachable.
Pixel dimensions for SVG icons are extracted from the SVG element's width and height attributes or viewBox. If the SVG has none of these, no dimensions are reported — the file is listed as present but with unknown dimensions. This is not an error, just a limitation of the SVG format.
Every check is ephemeral. There is no saved history, no scheduled re-checks, no email alerts when an icon disappears. These features are planned for a future Pro tier but are not yet built.
Headicons reports only what exists and what is missing. It does not generate icon images, recommend designs, or produce the files you need. You need to create or source your icons separately.
The tool fetches each page and icon exactly once at the moment you press "Check". A result that is correct at 10:00 may be stale at 10:01 if a deployment or CDN purge changes what is served.
How to contact support
Headicons does not yet have an email-based support channel. If you need help that is not covered by this page, please use a public issue tracker or contact the owner through the agen2ic framework.
No support mailbox is set up yet. Email-based support is a known requirement but has not been implemented. Until it is, the best way to report a problem is through the agen2ic project infrastructure. See needs.md in the site repository for the current owner actions required.