Debugging HTML5′s Offline Web Applications: Invalid MIME types, Manifest Parsing, and Resource Fetch Failures

Offline Web Applications in HTML5 are wonderful when they work. Visitors can view our site while on the subway or otherwise offline, and our sites load faster when they’re online.

Unfortunately, when things go awry, Offline Web Apps can be a horrible beast to debug. I wanted to outline some common things that can go wrong.

First off, the tools. The two places I look when Offline Web Apps aren’t going my way are (in Chrome or Safari 5+):

• The Resources tab
• The Error Console

Next, here’s a series of problems I’ve encountered, and what to do to fix them.

“Application Cache Error event: Invalid manifest mime type (text/plain)”

This error indicates that your web server is not passing the correct headers along with your .manifest file. It should be passing the type text/cache-manifest, but instead it’s passing text/plain.

If your web server is running Apache, the way to fix this is through the .htaccess file. Given that Apache is currently the most popular web server, used by 59.13% of all domains as of January 2011, chances are this is what you’ll need to do. For non-Apache servers, check out Mozilla Developer Network’s article on configuring server MIME types. You need to add the following line to your .htaccess file:

AddType text/cache-manifest .manifest

“Failed to parse manifest”

If you see this error, chances are you have a pretty big screw up in your manifest file. I got this error when the first line in my file had a misspelling: “CAHCE MANIFEST” instead of “CACHE MANIFEST”. Copy/paste is your friend.

“Failed to load resource” or “Resource fetch failed”

This error could mean you have an incorrect path or reference to a non-existing file in your manifest file.

Everything in your cache.manifest’s CACHE and NETWORK sections must be files, not folders. I saw this error when I accidentally included a folder instead of a file: /Folder/images/

You may also see this error if you have not accounted for all of your files. Do you have some images on the site that are not listed in the manifest? Remember, every single file in your domain must be accounted for in some way in the manifest file. An easy way to ensure this is to use the * wildcard in the online whitelist section (aka the NETWORK: section) of your manifest file.

When debugging this, look carefully at the Error console. If the manifest fails on a specific line, due to a mis-spelling perhaps, you’ll see in the error log the file it tried to fetch. You can search your manifest file for that line and fix/erase/comment the line out as needed. For example, if I have an image called kittens.jpg but instead refer to kitten.jpg in my manifest, here’s the error I’d see:

You are not seeing changes to your site show up… because the cache is cached

This one is enough to drive you mad, and Mark Pilgrim has a great writeup on it. There are two things you need to do in order to avoid this.
First, add the following to your .htaccess file if your web server is running Apache:

<Files the_name_of_your_manifest.manifest>
ExpiresActive On
ExpiresDefault "access"
</Files>

Next, make sure your manifest file has a commented out version number, like #v2.4:

CACHE MANIFEST
#v2.4 and counting!
CACHE:
#etc...

Every time you make a change to a file on your page, increment that version number and re-upload your cache.manifest file. The reason for doing this is that if you change a HTML file, say, about.html, the App Cache doesn’t know that. All it knows is it was told to cache about.html, and the cache manifest hasn’t changed, and perhaps the file size of about.html happens to be the same as it was before even though you changed the file… so none of your changes are showing up. Upping the version number in the cache.manifest file when you change any file on your site should help you avoid this headache.

What other issues have you seen with Offline Web Applications? Tell us about it in the comments.

Tags: app cache, application cache debugging, debugging offline web apps, failed to parse manifest, invalid manifest mime type, resource fetch failed