orange plastic blocks on white surface
Website Coding

When you add a website to the home screen on an Apple device, the device looks for an image file to use as the app icon. This specific file is called apple-touch-icon-precomposed.png and it is important for Apple devices to display the correct icon. Sometimes, website owners encounter issues because the devices try to load the icons from the root directory, leading to error messages if the files are not found or are set up incorrectly.

It’s important to fix these errors to ensure a smooth user experience, especially when a user bookmarks a site to their device’s home screen. The correct display of the icon represents the site and makes it more accessible. If there’s an issue with the setup or if the specified icon isn’t available, users may encounter a 404 error indicating that the file can’t be found. This reflects the need for troubleshooting. To avoid these errors, it’s important to ensure that the path is specified correctly, the file exists, and the icon dimensions are right.

Apple-touch-icon-precomposed.png error Explained

What is the Error?This error indicates that a website or web app is missing the specific icon files used by Apple devices when a user adds the site to their Home screen. This can result in a generic placeholder icon being displayed instead of a custom one.
Why Does it Happen?Missing files: The “apple-touch-icon-precomposed.png” and possibly “apple-touch-icon.png” files are not present in the root directory of the website. * Incorrect link tags: The HTML code referencing these icons may have errors in the file path or attributes. * Caching issues: The browser may be displaying an old version of the website, even when the icons are now in place.
How to Fix It1. Create the icons: Design (or use a generator) for the “apple-touch-icon.png” (and optionally “apple-touch-icon-precomposed.png”) in the recommended sizes (often 180×180 pixels, but check Apple’s guidelines for updates). 2. Upload to root directory: Place the icons in the root folder of your website’s file structure. 3. Add/Correct link tags: Include the following code in the <head> of your HTML, updating file names and sizes if necessary: html <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"> <link rel="apple-touch-icon-precomposed" sizes="180x180" href="/apple-touch-icon-precomposed.png"> 4. Clear Cache: Clear your browser cache and/or force refresh the website.
Best PracticesUse an online generator: Tools like help create the correct icon types and code. * Consider all devices: Apple’s developer guidelines list recommended sizes for various iPhones, iPads, etc. * Test on an Apple Device: Verify the icon appears correctly after saving it to the Home screen.

Key Takeaways

  • Apple devices need apple-touch-icon-precomposed.png to display website icons.
  • Errors occur when the icon file is missing or improperly configured.
  • Correct file path, existence, and size are key to preventing errors.

Understanding Apple Touch Icons

Apple touch icons serve as a visual bookmark for users when they add a website to the home screen of their Apple devices such as iPhones or iPads. These icons enhance the user experience and maintain the branding of websites on mobile devices.

Purpose and Importance of Apple Touch Icon

The Apple touch icon acts much like a favicon for iOS devices used when viewers save websites to their homescreen. This custom icon creates a visually appealing presence on the user’s device and aligns with the brand’s image. Having a touch-icon ensures a website stands out with a high-quality image that represents the site or app, rather than a miniature screenshot.

Differences between Apple-Touch-Icon and Apple-Touch-Icon-Precomposed

Apple-touch-icon.png is the standard filename and format for a touch icon. An alternative version, apple-touch-icon-precomposed.png, was previously used to represent a version of the icon without the additional gloss and rounded edges Apple’s iOS Safari browser would automatically apply. As of iOS 7, this precomposed element is no longer necessary, but its presence can trigger errors if the system still checks for it.

Standard Icon Specifications for iOS Devices

For a touch icon to display correctly on various Apple devices, developers should follow the standard icon specifications:

  • Sizes: Create an icon measuring 180×180 pixels for optimal display on all devices, including those with higher resolutions. Smaller screens and lower resolution displays automatically scale down the larger image as needed.
  • HTML Link: Place a HTML link tag in the head of your document to specify the location of the icon:
<link rel="apple-touch-icon" sizes="180x180" href="/path/to/apple-touch-icon.png">
  • File Location: Save the icon as apple-touch-icon.png at the root directory of the site unless a different path is specified in the HTML link tag.

By providing a custom touch icon for mobile devices, developers ensure that their web applications or websites present an inviting and easily recognizable shortcut on a user’s home screen for both iPhone and iPad devices.

Troubleshooting Apple Touch Icon Errors

When your website fails to supply the expected Apple touch icons, iOS devices and Safari might log errors. This section walks you through identifying why these issues arise and how to correct them on your site.

Step-by-step Troubleshooting Guide

1. Verify Missing Files

  • Check your root directory: Navigate to the root folder of your website (where your main index.html file resides). Use an FTP client or your hosting provider’s file manager.
  • Look for the missing icons: Do you see files named “apple-touch-icon.png” and/or “apple-touch-icon-precomposed.png”? If not, you need to create them.

2. Create the Icons (If Needed)

  • Design or generate: You can design the icons yourself (ideally 180×180 pixels, but check Apple’s specs for updates), or use an online generator like
  • Save in PNG format: Ensure you save both “apple-touch-icon.png” and “apple-touch-icon-precomposed.png” if you’re creating them yourself.

3. Upload to Root Directory

  • Place in the correct location: Upload both icon files directly into your website’s main root directory, the same place your index.html likely exists.

4. Check (or Add) Your HTML Link Tags

  • Locate the <head> section: Open your website’s main HTML file (usually index.html) in a code editor.
  • Add the following code within the <head> section, if it’s missing: HTML<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"> <link rel="apple-touch-icon-precomposed" sizes="180x180" href="/apple-touch-icon-precomposed.png">
  • Adjust as needed: If the file names or sizes are different, update the code accordingly.

5. Clear Cache and Test

  • Clear your browser’s cache: This varies by browser, but often you can go into your browser’s history settings to clear the cache and website data.
  • Force Refresh (Optional): On the website, try a force refresh (usually holding Ctrl/Cmd + Shift + R).
  • Test on an Apple device: Now attempt to add the website to your Home screen on an iPhone or iPad. The custom icon should appear.

Additional Tips:

  • If the error persists: Double-check for typos in your HTML code, and make sure the file paths are correct.
  • Precomposed vs. Non-Precomposed: Historically, the “precomposed” version of the icon prevented iOS from adding rounded corners and a shine effect. Modern iOS usually handles this automatically, so sometimes only “apple-touch-icon.png” is necessary.

Common Causes of Apple-Touch-Icon-Precomposed.png Errors

Several factors contribute to Apple touch icon errors. Primarily, iOS devices look for specific icon files when someone adds your website to their home screen. If these files are unavailable or incorrectly named, a 404 error may appear in your server logs. Typical causes include:

  • Missing Files: The absence of apple-touch-icon.png or apple-touch-icon-precomposed.png in the root directory.
  • Incorrect Filenames: The files exist, but are wrongly named or positioned in a different directory.
  • Improper HTML Markup: The <link rel="apple-touch-icon"> tag is either absent or inaccurately written within the HTML code.
  • Incompatible Sizes: iOS prefers specific icon dimensions, which if not met, can lead to errors.
  • Transparent Backgrounds: Safari expects icons with non-transparent backgrounds.

Fixing Apple Touch Icon Errors on Your Website

To fix errors related to Apple touch icons, follow these steps:

  1. Check Your HTML: Ensure you have the correct link tag within your <head> section. It should appear as: <link rel="apple-touch-icon" href="/apple-touch-icon.png">. This tells Safari where to find your icon.
  2. Verify Icon Sizes: Ensure your icon meets the size requirements. The standard size is 180×180 pixels for recent iOS devices.
  3. Upload Icons: Place the icon files named apple-touch-icon.png and apple-touch-icon-precomposed.png in your website’s root directory.
  4. Review Server Logs: Look at your server logs to see if the error persists.


  • The path you include in the href attribute needs to point to the correct file.
  • You might need to clear your device’s cache if changes don’t show up immediately.
  • Specific plugins or CMS settings might automatically look for these icons; ensure they are not removed or overwritten during updates.

By addressing the above common issues and implementing the provided fixes, you should be able to resolve most apple-touch-icon-precomposed.png errors and provide a better experience for users who bookmark your website to their home screens.

Frequently Asked Questions

When setting up a website, it’s common to run into issues with the apple-touch-icon. This section addresses common questions to help you get these icons working smoothly on your site.

Why am I encountering an error with my apple-touch-icon-precomposed.png on Android devices?

Android devices sometimes face errors with apple-touch-icon-precomposed.png because these devices may still send a request for this file. Originally meant for Apple devices, the requests happen when you bookmark a site or add it to the home screen. To fix this, ensure the file is in your root directory or specify its path in the head of your HTML.

How does apple-touch-icon-precomposed differ from apple-touch-icon?

The precomposed variant was meant to bypass the automatic glossy effect Apple devices added to the classic apple-touch-icon. With current iOS versions applying no extra styling to the icon, the precomposed version isn’t necessary anymore. However, its inclusion doesn’t harm and ensures legacy devices handle the icon correctly.

What are the steps to generate an apple-touch-icon-precomposed correctly?

To generate the icon:

  1. Create a PNG image with the correct dimensions.
  2. Save the image with the filename ‘apple-touch-icon-precomposed.png’.
  3. Place the file in the root directory of the website or define its location using a link tag in the head section of your HTML.

What are the recommended dimensions for an Apple touch icon?

Apple recommends creating an icon size of 180×180 pixels for higher resolution devices. This single size scales down for smaller devices, offering a one-size-fits-all solution that simplifies the icon setup process.

How can I specify an Apple touch icon in HTML?

Specify the icon in HTML by adding a link tag within the head of your document. For example:

<link rel="apple-touch-icon" href="path/to/apple-touch-icon.png">

Replace path/to/apple-touch-icon.png with the actual path to your icon file.

Is it possible to use an SVG file as an Apple touch icon?

No, Apple devices do not support SVG files for touch icons. These devices require PNG files for compatibility. Always use a PNG file for your apple-touch-icon to ensure widespread device support.

Similar Posts